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Preface 



Today, integration of software packages into computer algebra systems (CAS) 
and communication between CAS and other software systems using interprocess 
communication (IPC) protocols is gaining more and more relevancy for CAS 
users. For instance, one has written very efficient special purpose algorithms 
in a low-level language such as C/C++ and wishes to use them during a CAS 
session. Or software packages from the Internet should be integrated into a 
favourite CAS. 

At present, the general concept for integrating software packages into a CAS is 
to use IPC protocols. On Unix systems, protocols like these are usually imple- 
mented using sockets or can be emulated by communicating via pipes or files. 
They are very useful for communication between software systems running on 
different hosts of a computer network and also between one or more processes 
located on one host when no source code of the software packages is available. 
However, they are somewhat awkward and require a lot of communication over- 
head. When using such protocols the following actions have to be carried out 
to pass information, e.g. arguments of functions or return values, between pro- 
cesses or to call an external function of a communication partner (if function 
calls are supported by the protocol): 

1. CAS data are converted into data packages {information encoding) and 

2. transferred {copied physically) between the processes. 

3. Data packages are reconverted into CAS data or any other representation 
used by the communication partner {information decoding). 

Information encoding and decoding may be costly. Furthermore, since data 
are copied the amount of memory space that is needed to store the data is 
doubled. Especially in Computer Algebra, where symbolic computations often 
require a lot of memory {intermediate data swell) ^ this might cause problems. 




VI 



Preface 



This method is also not very useful when large amounts of data must be passed 
often during the execution of an algorithm and when the execution time of 
external functions is small compared to communication time. It also does not 
allow the linked software package to efficiently call internal functions of the CAS 
- on a C/C++ language level. 

A more flexible and efficient way to integrate C/C++ functions as well as com- 
plete software packages into a CAS is the author’s concept of dynamic modules. 

From the user’s point of view a dynamic module is similar to a CAS library 
package. It contains so-called module functions which are, in contrast to library 
functions^ not written in the CAS programming language but are machine code 
functions like the built-in functions of the CAS kernel. 

From a technical point of view a dynamic module is a special kind of a machine 
code library (mostly implemented as a shared library) which can be linked to a 
CAS at run-time. After the module is loaded, its module functions are made 
public to the interpreter of the CAS and propagated to the user like usual CAS 
functions. Using the concept of dynamic linking, the machine code of the mod- 
ule resides within the process environment of the CAS kernel and can directly 
access the internal methods and data structures of the kernel. Data exchange 
can be achieved by simply passing data references, e.g. C/C++ pointers. This is 
the fastest method possible, because no data needs to be physically copied and 
no other communication overhead is needed. Furthermore, time and memory 
usage is independent of the size of data to be exchanged. 

Loading as well as unloading dynamic modules can both be done at any time 
during a CAS session. Unloading a module means to unlink its machine code 
from the CAS kernel and to remove it from the memory to save system resources. 
Its module functions, however, are still memorized by the CAS interpreter. If 
they are needed later, the corresponding code is automatically reloaded. This 
feature allows the implementation of displacement and replacement strategies 
for dynamic modules, which are transparent to the user. 

The concept of dynamic modules is easy to use and increases the flexibility of 
a CAS with respect to the following aspects: 

• An open system: The CAS kernel is extendable by the user on a C/C++ 
language level with nearly any desired feature. 

• A universal shell to integrate, utilize and test various software packages 
in order to use them in combination to solve mathematical problems. 

• A modular and freely configurable CAS: special purpose functions like effi- 
cient numerical algorithms or IPC protocols can be developed, maintained 
and distributed as optional packages independently from the CAS kernel. 
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The variety of different packages and algorithms which can be utilized simultan- 
eously increases drastically. In this sense dynamic modules apply the principle 
of software integration to the broad field of mathematical applications. 



University of Paderborn (Germany), July 1998 

Andreas Sorgatz 
Email: andi@mupad.de 
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1. Introduction and Quick Start 



This chapter describes how to navigate through this book. It discusses the 
concept of dynamic modules in brief and demonstrates how to use, write and 
create them. References to related literature are given at the end of this chapter. 



1.1 How to Read this Manual 

This book is addressed to module users and developers. To write special or very 
efficient modules some technical knowledge is needed (see section 1.3). Table 
1.1 summarizes which chapters are relevant for which readers and can be used 
to navigate quickly through the chapters of this book: 



Table 1.1: Information Navigator 



Useful for. . . 




pters in this book 


users of modules 


(1.1.1) Quick Start 


(2) User Interface 


(10) Applications 


creating modules 


(3) Introduction 


(5) Creating 


(8) Platforms 


writing modules 


(4) Inside MuPAD 


(6) M/\P/-Manual 


(9) Problems 


all programmers 


(C) mmg-Manual 


(D) MAPI-\ndex 


(7) Specials 


all readers 


(B) Changes 


(A) CD-ROM 


(E) Glossary 



Chapter 1 contains general information introducing the following chapters. 

Chapter 2 contains help pages with a formal description of the user interface 
of dynamic modules. They are intended to be used as a reference manual. This 
chapter also describes how to access the plain text module online documenta- 
tion. This information is needed by all users who want to use modules. 
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Introduction and Quick Start 



Chapter 3 provides an introduction to the programming and the creation of 
dynamic modules to impart the basic ideas of module development and to 
motivate the technical descriptions of the following chapters. This information 
should be read by all those who want to write dynamic modules, but it may 
also be interesting for other readers. 

Chapter 4 provides technical information about the structure of the Mu PAD 
system and how it works inside. It contains essential information about data 
types, data representation as well as about the memory and module manage- 
ment. It is highly recommended to read this chapter before starting to program 
modules. However, to start quickly you may want to go through the examples 
in chapter 10 and the appendix D first and come back to chapter 4 later. 

Chapter 5 describes the module generator mmg which is to be used to compile 
and link C/C++ module source files into executable dynamic modules. This 
information is needed by those who want to create modules using their own 
sources or those distributed by Mu PAD. A short summary of the usage of the 
module generator is given in appendix C. 

Chapter 6 describes the MuPAD Application Programming Interface (MAPI). 
Subdivided according to the different aspects of module programming each 
section contains an introduction, formal descriptions of relevant MAPI routines, 
as well as examples following the idea of learning-by- doing. This chapter is 
intended to be used as a reference manual. A lexicographic index of all MAPI 
routines and variables is given in appendix D. This information is needed by 
those who want to develop or maintain modules. 

Chapter 7 informs about extensions of the module concept and related features 
of MuPAD that may be useful for your applications. 

Chapter 8 contains information about system dependencies and gives tech- 
nical advice on compiler support on different operating systems. Since chapter 
5 and appendix C describe the module creation on UNIX operating systems, 
users of Apple Macintosh^ and Windows 95/NT^ systems are asked to read 
chapter 8 for information about module creation on these platforms. 

Chapter 9 is a trouble shooting guide to help users to avoid (respectively 
work around) problems that may occur when starting to program modules and 
to integrate other software packages. 

Chapter 10 demonstrates more sophisticated applications of dynamic modules 
including their C/C++ source code, e.g. the usage of efficient numeric and num- 
ber theory packages or the integration of interprocess comunication protocols. 
Studying these examples provides further tips for writing dynamic modules. 

^Dec. 1997, developers version of release 1.4, prototype for Apple Macintosh PowerPC 
^Dec. 1997, developers version of release 1.4, prototype for Windows 95/NT 
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1.1.1 Remarks on the Paperback Version 

This book is also available as a Mu PAD hypertext document. Mu PAD examples 
marked with the label >> can be executed directly in cooperation with Mu PAD 
Release 1.4 and the module generator. 



1.1.2 Remarks on the CD-ROM Online Version 

Dynamic Modules are supported on most UNIX operating systems, on Apple 
Macintosh PowerPC and on Windows 95/NT systems. Due to the fact that 
remote control of external programs like compilers is easy and mostly compatible 
on all UNIX systems but cannot be supported in this way on Apple Macintosh 
or Windows 95/NT systems, many examples apply to the UNIX platform. 

All examples and application modules described in this book were tested with 
MuPAD 1.4.1 on a PC-compatible (Pentium) running Linux 2.0 and on a Sparc20 
workstation running Solaris 2.5. However, there should be no problem using, 
respectively porting, these examples to other platforms. Read appendix A and 
the description given with each application module to get detailed information. 

To read the online hypertext version of this book and to run the examples and 
application modules in combination with MuPAD 1.4, the accompanying CD- 
ROM must be installed first. Refer to appendix A for information about its 
contents, detailed installation instructions as well as about license agreements 
of these software packages. 

1.1.3 Technical Terms and Font Conventions 

To make it easy to distinguish MuPAD built-in, library and module functions 
-used on a MuPAD language level- from any other kind of functions used on a 
C/C-t--h level, the first ones are called functions whereas the second ones are 
always called routines in this book. 

Further technical terms used in this book are explained in the glossary 
of terms in appendix E. 

The following fonts are used to emphasize special terms, phrases and examples: 

• italic font: is used to introduce new technical terms, to quote section titles 
of other manuals and to emphasize special words and character strings. 

• typewrite font: is used for special or reserved names, for examples, and 
for MuPAD and C/C+-|- code. 

• bold face: is used for very important notes and technical information. 
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Introduction and Quick Start 



1.2 The Concept in Brief 

Dynamic modules (short: modules) are machine code library packages -mostly 
implemented as shared libraries respectively dynamic link libraries- that can be 
loaded and executed during a Mu PAD session. CAS user functions which are 
defined in a dynamic module are called module functions. They are written in 
the general purpose and widely used programming language C/C-I-+ and are 
compiled and linked to a special kind of a machine code library. 

For loading a dynamic module methods of dynamic linking are used. Therefore, 
within a module function the programmer cannot only use those functions and 
variables visible within the Mu PAD language but also all (documented) internal 
routines and variables of the Mu PAD kernel. This makes module functions as 
fast and fiexible as if they were implemented in the Mu PAD kernel itself. 

Dynamic modules can be unloaded at any time during a Mu PAD session in order 
to save memory resources. This can be done explicitly by the user and also by 
automatically displacing and replacing strategies of the module manager (e.g. 
aging). If a module function has to be executed after its machine code has been 
unloaded, it is reloaded automatically and transparently for the user. 

To make programming of module functions easy. Mu PAD provides an Applica- 
tion Programming Interface (MAPI). It consists of C/C++ macros and routines 
to be used to declare module functions, to access kernel objects, to construct, 
manipulate and convert MuPAD and C/C++ data structures and more. A 
detailed description of these routines is given in chapter 6. 

To create an executable dynamic module a special preprocessor is used - the 
so-called module generator (mmg). It analyzes the user’s C/C++ module source 
code and adds additional code which is needed by the MuPAD kernel to manage 
a module. After that, the module generator uses the C++ compiler and linker 
of the operating system to create machine code. A detailed description of the 
module generator is given in chapter 5. 



1.2.1 Advantages of Dynamic Modules 

In general module functions are much faster than library functions because they 
need not be interpreted by the MuPAD system but can be directly executed by 
the computer’s processing unit. Also operating on the internal representation 
of MuPAD data structures -by utilizing internal kernel routines- is often signi- 
ficantly more efficient than using the high-level language. 

Furthermore, implementing module functions in a low-level programming lan- 
guage such as C/C++ is very fiexible because one can access the entire oper- 
ating system and the computer’s hardware. In contrast to this, programming 
languages of computer algebra systems (CAS) are intended to be used for math- 
ematical algorithms and mostly do not provide such features and users can only 
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implement algorithms that are based on functions and data types which are 
part of this language. Therefore, in conventional C/C++ based CAS, real ex- 
tensions like an interprocess communication protocol or a new floating point 
arithmetic cannot be integrated by the user but only by the CAS developers. 

Using the concept of dynamic modules, the user can extend the Mu PAD ker- 
nel with nearly no restrictions. Many mathematical public domain software 
packages and special purpose algorithms are written in C/C++. They can be 
integrated into Mu PAD very easily and efficiently. See chapter 10 for examples. 



1.2.2 How to Use Modules 

Dynamic modules and module functions can be used in the same way as library 
packages and library functions. While library packages are loaded with the 
command loadlib^ for modules the function module is used. The following 
demonstration loads the module stdmod which is distributed with all Mu PAD 
systems that support dynamic modules and is therefore used as an example: 

>> reset 0 : 

moduleC ''stdmod" ); 

stdmod 

Next, the function info (refer to [50, p. 363]) is used to display the user in- 
formation text of the module. It behaves on dynamic modules exactly as on 
Mu PAD library packages: 

>> info( stdmod ): 

Module: ^ stdmod^ created on 08. Apr. 98 by mmg R- 1.4.0 
Module: Module Management Utilities 

Interface: 

stdmod:: age, stdmod:: doc, stdmod: : help, 

stdmod: ‘.max, stdmod :: stat , stdmod :: which 

After a module is loaded, its functions can be executed in the same way as library 
functions using the syntax package: :function(). In the following example, 
the function which returns the pathname of a dynamic module: 

>> stdmod: :which( "stdmod" ); 

" /home/andi/mupad/ i386/modules/stdmod . mdm" 



^Refer to the MuPAD User’s Manual [50, p. 384]. 
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Introduction and Quick Start 



Like library functions, also module functions can be exported from a module 
domain with the command export (refer to [50, p. 324]) to make their names 
globally known: 

>> export ( stdmod ) : 
which( "stdmod" ); 

"/home/andi/mupad/i386/modules/stdmod.mdm" 

A special feature of dynamic modules is that their machine code can be unloaded 
-i.e. removed from the main memory- at any time during the Mu PAD session. 
The command module: : displace is used for this: 

>> module :: displace ( stdmod ): 
which ("stdmod") ; 

"/home/andi/mupad/i386/modules/stdmod.mdm" 

As one can see, even if a dynamic module was unloaded, its functions are still 
known to the Mu PAD system. If one of them has to be executed later on, the 
corresponding machine code is automatically reloaded by the module manager. 

Another useful command to access module functions is module: :func. It can 
be used to access a specific module function without explicitly loading the cor- 
responding module via module. Like in the previous example, the machine code 
of this function is (re-) loaded on demand^ transparently to the user. 

>> where := module : :func( "stdmod", "which" ): 
where; 

where( "stdmod" ); 
which 

"/home/ andi/mupad/ i386/modules/ stdmod .mdm" 

A complete and detailed description of all Mu PAD functions available for module 
management is given in chapter 2. 



1.2.3 How to Write and Create Modules 

The following example shows the complete user C/C-I-+ source code of a dy- 
namic module named sample. It consists of one module function date() which 
returns the current date and time in form of a Mu PAD character string.^ 



^This online example does not work on operating systems other than UNIX. 
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>> f print ( Unquoted, Text, /tmp/ sample. C" , ” 



MFUNC( date, MCnop ) 


/* 


Begin of module function 


*/ 


{ time.t clck; 


/* 


Local variable C/C++ 


*/ 


char *cstr; 


/* 


Local variable C/C++ 


*/ 


MTcell mstr; 


/* 


Local variable MuPAD 


*/ 


time(&clck) ; 


/* 


Gets current time 


*/ 


cstr = ctime(&clck) ; 


/* 


Converts into a string 


*/ 


cstr [strlen(cstr)-!] = 0; 


/* 


Removes carriage return 


*/ 


mstr = MFstring(cstr) ; 


/* 


Converts to MuPAD 


*/ 


MFreturnC mstr ) ; 


/* 


Returns to MuPAD 


*/ 


} MFEND 


/* 


End of module function 


*/ 



' ); 



To create an executable module the Mu PAD module generator mmg is used. 
Option -V switches the verbose mode on. Option -V includes a version inform- 
ation string into the module and option -gnu instructs mmg to use the GNU 
C++ compiler instead of the standard compiler of the operating system.^ 

>> systemC MDM_PATH . . /share/bin/mmg -v -V ^Demo^ 

/tmp/sample.C -op /tmp ; 
file /tmp/sample.mdm" 

): 

MMG — MuPAD-Module-Generator — V- 1.4.0 Feb. 98 
Mesg. : Scanning source file . . . 

Mesg.: 1 function(s) and 0 option(s) found in 13 lines 
Mesg. : Creating extended module code . . . 

Mesg. : Compiling extended module code . . . 

[...] 

Mesg. : Linking dynamic module . . . 

[...] 

Mesg.: Ok 

sample. mdm: ELF 32-bit LSB shared object, Intel 80386 

A detailed description of the module generator mmg and its options is given in 
chapter 5. A short reference manual is available in appendix C. 

With this, the dynamic module sample. mdm (binary file) is placed in the dir- 
ectory /tmp and can be used in a Mu PAD session as demonstrated below: 
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» module( Path='7tmp*' , "sample" ): 
info( sample ): 

Module: ^sample' created on 04. May. 98 by mmg R-1.4.0 
Demo 

Interface: 

sample: : date, sample:: doc 

>> sample: :date() ; 

"Mon May 4 20:52:07 1998" 

1.3 Where to Find Further Information 

Before reading this manual to learn how to write and create dynamic modules, 
the user should be familiar with the usage of Mu PAD, with the programming 
language C as well as with some basics of C++. 

Concerning the Mu PAD language the user should have read and understood at 
least the following sections of the MuPAD User^s Manual [50]: 

• 2.2 Details of Evaluation^ which explains the representation of MuPAD 
expressions and what the term evaluation means in MuPAD. 

• 2.3 Basic Types^ which describes the MuPAD type concept and lists all 
data types that are available in MuPAD. 

• 2.10 Manipulation of Objects^ which introduces the methods to access and 
manipulate sub-expressions of MuPAD objects (trees). 

• Appendix A Tables^ which contains tables giving an overview on MuPAD 
data types and their operands. 

An introduction to the programming language C is given in Kernighan and 
Ritchie’s book The C programming language [17]. 

A detailed description of the programming language C++ can be found in the 
book of B. Stroustroup The C+-h programming language [49]. 

More detailed technical information about the concept of dynamic modules and 
its implementation for MuPAD 1.2.2 are given in the MuPAD Report Dyna- 
mische Module - Eine Verwaltung fiir Maschinencode-Objekte zur Steigerung 
der Effizienz und Flexibilitdt von Computeralgebra-Systemen [40] (German). 

Current information about the development of MuPAD and the module concept 
are available via the World- Wide- Web^. 



^http : //www . mupad . de 
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1.4 Challenges and Contributions 

It is the developer’s concern to provide the general purpose computer algebra 
system Mu PAD as an open system^ that can easily be integrated into the user’s 
working environment and allows to interface any kind of (mathematical) soft- 
ware packages. Examples can be found in chapter 10. 

Re-using existing software packages -within the academic research community 
these are often available as public domain or freeware via anonymous ftp- and 
interfacing special purpose algorithms from inside Mu PAD is the basis for eco- 
nomical and efficient usage of computer algebra systems in a broad field of 
mathematical applications for researchers as well as for engineers. 

Furthermore, many mathematical software packages are made available in form 
of C or C++ class libraries, e.g. Asap, Gmp, Magnum, Mp, Imsl, Nagc, Ntl, 
GB or RealSolVING which are described in chapter 10. These libraries provide 
either no or only a very simple interactive user interface. However, Mu PAD 
can be used as a very flexible and powerful mathematical shell to interface 
algorithms utilizing these packages. 

For information about dynamic modules and module interfaces currently avail- 
able refer to the Mu PAD web site^. 

If you would like to make contributions and would like to share modules, soft- 
ware packages or algorithms with the Mu PAD user community, please contact 
the author^ or the Mu PAD team.^ 



®Email: andiOmupad.de 
^Email: distributionOmupad.de 




2. Modules User Interface 



This chapter describes the Mu PAD functions provided to load and unload mod- 
ules, to call module functions and to control the module management. They are 
divided into basic functions available as kernel built-in functions and functions 
for extended module management available with the Mu PAD library package 
moduleh 

At the end of this chapter, the representation of dynamic modules as a Mu PAD 
domain and aspects of module documentation are discussed. 



2.1 Basic Functions to Access Modules 

The kernel provides the built-in functions external, loadmod and unloadmod 
as the basic interface to access dynamic modules. They are described here 
because their names appear in descriptions of library functions and in error 
messages. However, the user should use the functions of the library package 
module described in section 2.2 to access modules and module functions. 

external - Creates a module function environment 

V1.4 

Call; 

external (mname, fname) 

Parameter: 

mname — character string, name of a module 

fname — character string, name of a module function 

^This library package uses the dynamic module stdmod, which is distributed with all 
Mu PAD versions that support the usage of modules. 
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Synopsis: 

external creates and returns the function environment (DOM_FUNC_ENV) of the 
module function mname: tfname. It can be used to assign the handle of a mod- 
ule function to a variable and to execute it without loading the corresponding 
module explicitly via loadmod. The module manager will load its machine code 
automatically and transparently to the user at the time it is needed. In contrast 
to the function loadmod, external does not define a module domain, external 
is a kernel function. 

If additionally the file mname. exists (see section 7.2), it is expected to con- 
tain Mu PAD objects which are loaded and linked to the function environment. If 
an error occurs while loading these objects, a warning is displayed and Mu PAD 
retries to load them with each call of the corresponding module function. 

Changes: 

1.4 — The order of the function arguments changed. 

Examples: 

>> Where:= external (’’stdmod" , "which") : 

Where ("stdmod") ; 

"/usr/local/MuPAD/i386/modules" 

See also: 

export, loadmod, unloadmod 



loadmod - Loads a module 

V1.4 

Call: 

loadmod (mname) 
loadmod 0 

Parameter: 

mnajae — character string, name of a module 

Synopsis: 

loadmod loads the module mname and defines -similar to loadlib when loading 
a library package- a mqdule domain named mname. If the global identifier mname 
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had any value before, this is overwritten and a warning message is displayed, 
loadmod is a kernel function. It returns the newly created module domain. 

The name mname must be given without a path and suffix. Paths and the module 
search order can be changed using the Mu PAD variable READ_PATH. 

If mname is not a pseudo module (section 4.7.1) the corresponding module binary 
file name.mdm is first searched for in the paths given by READ_PATH, then in the 
current directory and finally in the module default directory.^ If it cannot be 
loaded, the evaluation is aborted with an error message. 

If additionally the file mname. exists (see section 7.2), it is expected to con- 
tain Mu PAD objects which are loaded and linked to the module domain respect- 
ively to the function environments of the module functions. If an error occurs 
while loading these objects, a warning message is displayed and Mu PAD retries 
to load them with each call of the corresponding module function. 

The machine code of mname is only loaded if it is not already linked, if it was 
automatically displaced or if it was unloaded by the user. The module domain 
will be recreated with each call of loadmod and the file mname. is reloaded. 

In addition to mname. mdm a text file mname. md/i (see section 2.4) may exist. It 
is expected to contain formatted plain text help pages for this module. They 
can be read using the module function mname: :doc(). 

Calling loadmod without any arguments it returns TRUE if the current kernel 
supports dynamic modules and FALSE otherwise. 

Examples: 

>> loadmod (" stdmod" ) ; worker:= loadmod("slave") ; 

stdmod 

slave 



See also: 

export, external, info, loadlib, unloadmod 



unloadmod - Unloads a module 

V1.4 

Call: 

unloadmodC < mname <, Force > >) 



^On Apple Macintosh PowerPC and Windows 95/NT systems the search order may differ. 
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Parameter: 

mname — character string, name of a module 

Synopsis: 

unloadmod displaces the machine code of the module mname from memory. If 
no argument is given, Mu PAD tries to unload all modules. Identifiers that were 
defined and assigned by use of the functions loadmod and external remain 
unchanged and valid, unloadmod is a kernel function. It returns the object of 
type D0M_NULL. 

If a function of a displaced module is called, the corresponding machine code is 
reloaded automatically, transparently to the user. In contrast to the function 
loadmod in this case no global identifiers are defined respectively redefined. 

If an error occurs while unloading a module, unloadmod aborts the current 
evaluation with an error message. This is also done if unloadmod tries to unload 
a module that was declared to be static (refer to section 4.7.1). 

The option Force enables the user to explicitly unload a static module. The 
user has to make sure that its machine code is not needed anymore! 

Examples: 

>> loadmod ( "stdmod" ) : 
unloadmod 0 : 

stdmod: : which ("stdmod") ; 

"/usr/local/MuPAD/i386/modules" 

See also: 

external, loadmod 



2.2 Extended Module Management 

The library package module implements the user interface to access modules 
and module functions and to control the module management. It provides 
functions to read module online documentation (refer to section 2.4), to control 
the module displacement strategies and to display information about currently 
loaded modules. 

This package uses the built-in functions external, loadmod and unloadmod 
(section 2.1) as well as the dynamic module stdmod.^ The following library 
functions are available: age, displace, func, help, load, max, stat, which. 

^stdmod is distributed with all Mu PAD versions which support dynamic modules. 




Extended Module Management 



15 



age - Controls module aging 

V1.4 

Call: 

age( < maxage <, interval > >) 

Parameter: 

maxage — integer in the range [0..3600] 

interval — integer in the range [1..60] 

Synopsis: 

If aging is active, modules are displaced when they reach a maximum age de- 
fined by the user. The age of a module is measured in seconds that pass between 
two successive accesses to this module, i.e. loading its machine code or calling 
one of its module functions. 

age returns the current maximum age for modules. If maxage is greater than 
zero, the maximum age is set to it and module aging is activated. The optional 
parameter interval specifies the minimum time interval between two successive 
calls of the aging algorithm. If maxage is zero, module aging is deactivated. This 
function uses the module function stdmod: rage. 

Examples: 

>> module: :age(300, 30) : 
module : : age(60) ; 

60 



See also: 

module : : max, module : : stat 



displace - Unloads a module 

V1.4 

Call: 

displaceC < mod >) 



Parameter: 

mod 



string, identifier or module domain 
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Synopsis: 

displace unloads the machine code of the module mod from the main memory 
by utilizing the built-in function unloadmod (page 13). 

Examples: 

» module (stdmod) : module :: displace (stdmod) : type(stdmod) ; 
DOM.DOMAIN 



See also: 

module: :load, unloadmod 



func - Creates a module function environment 

V1.4 

Call: 

func (mod, fun) 

Parameter: 

mod — string, identifier or module domain 

fun — string, identifier or function environment 

Synopsis: 

func creates and returns the function environment (DOM_FUNC_ENV) of the mod- 
ule function mod: :fun by utilizing the built-in function external (page 11). 
module("mod","fun") is a shortcut for module: :func("mod","fun"). 

Changes: 

1.4 — The order of the parameter mod and fun switched. 

Examples: 

» module: :func(stdmod, "which”) (’'stdmod”) ; 

" /home/andi/MuP AD/ i386/modules/ stdmod .mdm” 



See also: 

external, loadmod 
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help - Displays module online documentation 

V1.4 

Call: 

helpCmod <, fun >) 

Parameter: 

mod — string, identifier or module domain 

fun — string, identifier or function environment 

Synopsis: 

help displays the introductional page of the plain text online documentation 
of the module mod respectively the help page of the module function mod : :fun. 
Both descriptions are read-out from the file mod .mdh which has a special format. 
It consists of a so-called general information page, followed by a list of module 
function help pages. Refer to section 3.4 for details. If the help file mod. mdh 
cannot be found, help aborts the current evaluation with an error message. 

The search paths and order for the help file is equivalent to the one used by 
the function which. In addition to this, the help file is also searched for in the 
MuPAD plain text help directory $MuPAD_ROOT_PATH/share/doc/ascii. This 
function uses the module function stdmod: :help. Also refer to section 2.4. 

Examples: 

>> module: :help(stdmod) : 

MODULE: 

stdmod - MuPAD standard module (module management) 
DESCRIPTION: 

This module contains a set of elementary functions to con- 
trol the module management. They are used by the library 
package "module" . 

INTERFACE: 

age, help, max, stat, which 



See also: 
module : : which 
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load - Loads a module 

V1.4 

Call: 

load (mod) 

Parameter: 

mod — string, identifier or module domain 

Synopsis: 

load loads the module mod and returns its module domain by utilizing the built- 
in function loadmod (page 12). The function call module (mod) is a shortcut for 
module: : load (mod) 

Changes: 

1.4 — module (Path=pat/i, mod) specifies to look for the module in 

the directory path first. 



Examples: 

>> module (stdmod) ; 
type(stdmod) ; 



stdmod 

DOM.DOMAIN 



See also: 

loadmod, module: : displace 



max - Limits number of simultaneously loadable modules 

V1.4 

Call: 

max( < num >) 

Parameter: 



num 



integer in the range [1..256] 
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Synopsis: 

max returns the maximum number of simultaneously loadable modules (default 
16). If num is out of range or is less than the number of currently loaded modules, 
max aborts with an error message. Otherwise, the new maximum is set to num. 

If the maximum number of simultaneously loadable modules is reached, any 
additional module subsequently displaces a previously loaded one chosen by 
the method least recently used, max uses the module function stdmod: imaix. 

Examples: 

>> module: : max 0 , module :: max (5) ; 

0, 5 

See also: 

module : : age, module : : stat 



stat - Displays the state of the module management 

VL4 

Call: 
stat 0 

Synopsis: 

stat displays the current state of the module management by utilizing the mod- 
ule function stdmod: :stat. Besides the names of all currently loaded modules, 
the function displays some internal information. 

Examples: 

>> module : : stat () : 



M-Path : /home/andi/mupad/i386/modules 

[...] 



stdmod : age= 0 | flags = {> 

mp : age= 241 | flags = {static} 



See also: 

module : : age, module : :max 
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which - Returns the pathname of a module 

V1.4 

Call: 

which (mod) 

Parameter: 

mod — string, identifier or module domain 

Synopsis: 

which returns the full pathname of the module mod respectively the value FAIL 
if the module file cannot be found. The file mod. mdm is first searched for in the 
paths given by the Mu PAD variable READ_PATH, then in the current directory 
and finally in the module default directory. 

For pseudo modules, the function always returns the module default directory, 
which is usually $MuPAD_R00T_PATH/5i/5^em/modules/. 

Examples: 

>> module: : which ( stdmod ); 

'•/home/andi/MuPAD/i386/modules/stdmod.mdm‘' 



>> module: : which ( "myrnodule” ); 
” . /mymodule" 

>> module: : which ( "muff' ); 

FAIL 



See also: 

module : : help, module : : load 
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2.3 Module Domain Representation 

Like Mu PAD library packages, modules are represented as domains - the so- 
called module domain (see page 38). Refer to the MuPAD User^s Manual [50] 
section 2.3.18 for detailed information about domains in MuPAD (D0M_D0MAIN). 

Furthermore, library packages and modules both provide the same predefined 
default methods which implies that modules are used in exactly the same way 
as the well known library packages. For example, module functions are called 
using the syntax module: ifuncO- The command inf o(module) displays in- 
formation about module and exiport (module) makes all local methods defined 
in the interface of module global. Examples are given in section 1.2.2. 

The concept of domains allows to implement user-defined data types in the 
MuPAD programming language. Since modules are represented as domains they 
can be used to define new data types by utilizing the flexibility and efficiency 
of the C/C-|--|- programming language. 

More information about predefined and reserved methods of module domains 
are given in section 3.3. For information about user-defined data types refer to 
the MuPAD User’s Manual [50] section 2.3.19. 



2.4 Module Online Documentation 

Module online documentation may be provided in form of a simple formatted 
plain text file mod.mdh and can be displayed during a MuPAD session -after 
loading the module mod- using the module function mod : :doc. 

The module documentation file mod . mdh has a special format which is specified 
in section 3.4. It consists of a so-called general information page followed by a 
list of module function help pages. 

The function call mod: :doc() displays the general information page of the 
module mod whereas mod: :doc("func”) displays the help page of the module 
function mod: :func. The module function mod: :doc interfaces the library 
function module: :help (refer to page 17). 




3. Introduction to Module 
Programming 



This chapter gives an overview of the tasks which need to be carried out for 
writing and creating modules. General aspects of the module source code and 
the compilation of modules are discussed. Special module methods are listed 
and the format of module documentation files is explained. 



3.1 Module Source Code 

Module sources can consist of any C/C++ code. To make this code available 
in a MuPAD session, interface functions, the so-called module functions^ have to 
be implemented. They can be executed by the user during a session and may 
internally use any other C/C++ code and corresponding machine code linked 
to the module. 

Since module functions become a dynamic part of the MuPAD interpreter when 
loading the module, they must have a very special format. They have to be 
always defined by use of the keyword MFUNC (see section 6.2) and they use a 
special style for receiving incoming function arguments (section 6.2.1) and for 
returning function results (section 6.2.2). 

Implementing modules is facilitated by the MuPAD Application Programming 
Interface (MAPI). It provides a set of definements, variables and routines for 
creating, manipulating and converting MuPAD objects and for accessing essen- 
tial MuPAD kernel routines as well as built-in and library functions. 

Three levels of writing modules can be distinguished which require an increasing 
knowledge about the internal structure of the MuPAD system: 

1. Operating on C/C-f--h data types: This is very simple. One can use the 
conversion routines described in section 6.5 to convert incoming function 
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arguments from Mu PAD into C/C++ data types and vice versa to convert 
function results from C/C++ into Mu PAD data types^ 

To operate on constructed Mu PAD data such as lists (D0M_LIST), sets 
(DOM-SET) and polynomials (D0M_P0LY). Read also 6.6, 6.7.1 and 6.7. 

2. Integration of software packages: This requires the implementation of data 
conversion routines. If the software package uses data types which are 
directly based on C/C++ types, data conversion can be done as described 
above. If special formats are used, e.g. for arbitrary precision numbers 
(section 4.5.4), new conversion routines have to be written by the user. 
Examples for this are given with the applications in chapter 10. 

Linking external software packages to Mu PAD, might cause naming con- 
flicts in some rare cases. Refer to section 9, Trouble Shooting, to read how 
to avoid respectively work around these problems. 

3. Implementing Mu PAD algorithms: This requires the user to know about 
the structure of Mu PAD data types and how to construct and manipulate 
them. Refer to sections 6.6, 6.7 and 4.4 for details. 

It is strongly recommended to read chapter 4, Inside MuPAD, to get basic 
knowledge about the internal structure of Mu PAD, its memory and module 
management system and the representation of Mu PAD data types. 



3.2 Creating Binary Code 

To compile and link module source code into an executable module the so-called 
module generator (mmg, chapter 5) is used. Calling mmg, the user’s source code 
is analyzed and extended by some additional code for the module management. 
It is then compiled and linked into a loadable dynamic module which can be 
used instantly from within MuPAD. 

As a default, the standard C++ compiler of the operating system is used, but 
this can be changed by the user to use either the GNU C++ compiler or any 
other one. Refer to section 5.2.1 and 5.2.2 for detailed information. 

As usual, modules can use any functions of other C/C++ shared libraries, 
too. The module generator just must be told which libraries have to be linked 
additionally. Libraries compiled from other programming languages, e.g. such 
as Pascal, may also be integrated if this is supported by the C++ compiler and 
linker of the corresponding operating system. Refer to section 5.2 for additional 
information. 



^ Note; Conversion is limited to the hardware representation of machine numbers. 
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3.3 Predefined Methods and Reserved Names 

Like Mu PAD library packages, module domains contain some predefined meth- 
ods. These are reserved and should not be redefined by the user: 

• name contains the user-defined name of the module. 

• key contains the internal name of the module (typically equal to name). 

• info is a short user information string which can be displayed after loading 
the module using the function info (also see page 5). This string can be 
set with the module generator option -V. 

• interface contains the set of names of those functions which serve as 
the user interface of this module. This information is displayed by the 
function info and is used by export (also see page 6) to make these 
names global within Mu PAD. 

• doc displays the module plain text online documentation if available. 
Refer to section 2.4 for details. 

In addition to these names, the following domain methods have a special mean- 
ing to dynamic modules. They are allowed to be defined (respectively redefined) 
by the user when writing modules: 

• initmod is executed directly after the module was loaded and the module 
domain is created using the function loadmod. It can be used to initialize 
the module or to display control messages. 

• new is a special domain method which is usually used for creating new 
domain elements. If ddd is a domain (D0M_D0MAIN) then the function call 
ddd() is a shortcut for ddd: :new(). 

Refer to the MuPAD User’s Manual [50] section 2.3.19.1, Internally Used Meth- 
ods to read about other special methods of module and library domains. 



3.4 Online Documentation File Format 

The plain text file mod . mdh can be used to provide online documentation for 
a dynamic module mod. This file must be placed either in the same directory 
as the module file mod ,mdm itself or in the MuPAD directory for plain text help 
pages^. Otherwise it may not be found by the MuPAD kernel. Refer to section 

2.4 to read about displaying these documents within a MuPAD session. 

^On UNIX operating systems this is $MuPAD_ROOT_PATH/share/doc/ascii/, where 
$MuPAD_R00T_PATH is the directory where MuPAD is installed in. 
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The format of the plain text documentation file is very simple. The file starts 
with any text that is expected to be the general information page of the corres- 
ponding module. The rest of the file consists of text blocks of the format: 



<!— BEGIN-FUNC func — > 

help page for function mod : :func 

<!— END-FUNC — > 

Any other text outside of these blocks is ignored. This kind of start and end 
tags for help pages was chosen to enable the user to include these pages into 
Internet web pages without reformatting them. However, no further HTML 
code must be used within the module documentation file. 

To keep the layout of all module online documentation uniform and to make 
reading them easy for the user, writers should follow the conventions of the 
module documentation style: 

• The module documentation should always be written in English to make 
it readable for users all over the world. 

• The documentation should be subdivided into a general information page 
and help pages for all module functions as described below. 

• Some meaningful examples should be given with each module function 
help page. Because examples often tell more than words can say. 

• The length of lines should not exceed 70 characters to support reading 
this documentation on small computer screens respectively within small 
application windows. 



3.4.1 General Information Page 

The general information page is the front page of every module documentation. 

It consists of three sections which introduce the module to the user: 

1. MODULE: This section contains the module name and a short, one line 
description of the module. 

2. DESCRIPTION: This section contains a detailed description of the mod- 
ule including information about algorithms or external software packages 
that are integrated, an ftp address where this module can be copied from 
-if it is freely available- and an email address for bug reports. 
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3. INTERFACE: This section contains the list of module functions which 
are available with this module and are intended to be used directly. 



The example shows the general information page of the dynamic module stdmod: 



MODULE: 

stdmod - MuPAD standard module (module management) 

DESCRIPTION: 

The module "stdmod" contains a set of basic functions to control the 
module management and to display module online documentation. It is 
distributed with MuPAD and is used by the library package "module" 
which perfoms the user interface to the module manager. Please report 
bugs via email to bugsOmupad.de. 

INTERFACE: 

age, help, max, stat, which 



3.4.2 Function Help Pages 

The help pages of module functions consist of six sections whose format and 
semantics is similar to that used in MuPAD hypertext help pages and also 
compares to the format of UNIX manuals (man pages): 

1. FUNCTION: This section contains the name and a short, one line de- 
scription of this module function. 

2. SYNOPSIS: This section shows how the function has to be called, includ- 
ing its parameter(s) and optional arguments. 

3. PARAMETER: This section contains a short, one line description of every 
parameter and option listed in the SYNOPSIS field. The description 
should inform about the expected data types and their semantics. 

4. DESCRIPTION: This section contains a detailed description of the func- 
tion including information about its parameter, return value and, if ne- 
cessary or useful, the algorithm that is used. 

5. EXAMPLES: This section contains one or more examples consisting of 
alternating input and output regions. 

6. SEE ALSO: This section contains a list of related MuPAD functions. 



The example below shows the help page of the module function stdmod : : which. 
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<!— BEGIN-FUNC which --> 

FUNCTION: 

which - Returns the pathname of a module 
SYNOPSIS: 

stdmod: : which ( mstring ) 

PARAMETER: 

mstring - character string, name of a module 
DESCRIPTION: 

Returns the pathname of the module "mstring" or the value FAIL if it 
cannot be found. The file "mstring. mdm" is first searched for in the 
paths given by the MuPAD variable READ^PATH, then in the current work- 
ing directory and finally in the default module directory. For pseudo 
modules, the function always returns the default module directory, 
usually "$MuPAD_ROOT^PATH/<SYSTEM>/modules" . 

EXAMPLES : 

Call #1: stdmod: : which ( "stdmod" ); 

"stdmod. mdm" 

Call #2: stdmod: : which ( "muff" ); 

FAIL 

SEE ALSO: 

stdmod: : help, module :: which 
<!— END-FUNC — > 



4. Inside MuPAD 



This chapter provides technical information about the MuPAD system in gen- 
eral and the MuPAD kernel including the interpreter, the memory management 
system, essential MuPAD data types and their internal representation as well as 
the module management system. 



4.1 System Components 

The MuPAD system consists of four components (figure 4.1): The front end 
(notebook, graphics and debugger) acts as a convenient user interface to the 
features of the MuPAD kernel The kernel is the heart of the MuPAD system. It 
defines the high-level programming language of MuPAD as well as the basic set of 
very efficient functions for arbitrary precision arithmetic and the manipulation 
of symbolic expressions, the so-called built-in functions. 
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Figure 4.1: Components of the MuPAD System 

The third component is the MuPAD library which contains most of the math- 
ematical knowledge of the MuPAD system. It consists of so-called library pack- 
ages containing library functions. They implement sophisticated high-level al- 
gorithms such as symbolic integration or the factorization of multivariate poly- 
nomials. Library functions are written in the MuPAD programming language 
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and are interpreted (evaluated) by the kernel at run-time. Writing library func- 
tions is easy and comfortable since the MuPAD language provides high-level 
data structures such as lists, tables, arrays etc. and a powerful instruction set 
for implementing complex mathematical algorithms. However, due to the fact 
that this language was designed for mathematical computations, it is somewhat 
restricted. For example, users cannot implement functions which directly access 
machine floating point numbers or integrate foreign software packages on this 
programming level. Both require a low-level language such as C/C++. 

Last but not least there are dynamic modules. They are dynamic kernel ex- 
tensions which can be loaded and also be unloaded during a MuPAD session. 
They consist of so-called module functions^ written in the C/C++ programming 
language, and enable users to extend the MuPAD kernel. 



4.2 The Kernel 

Figure 4.2 shows a simplifled diagram of the MuPAD kernel. It consists of four 
main components: the memory management system (section 4.4, MAMMUT 
[30]), the arbitrary precision arithmetic package (PARI [4]), the module man- 
ager (section 4.7, MDM [40]) and the interpreter (section 4.3) including the I/O 
system^ the evaluator and simplifier as well as all built-in functions. 
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Figure 4.2: Components of the MuPAD Kernel 

MuPAD built-in functions are written in C/C++ and compiled to machine code. 
Due to this fact, they are very fast in contrast to the interpreted library func- 
tions. They are a static part of the kernel. Thus they cannot be changed or 
extended by the user. Kernel extensions can be implemented by utilizing the 
concept of dynamic modules. The following sections provide brief introductions 
to the MuPAD interpreter, the memory and module management system. 



4.3 The Interpreter 

The task of the MuPAD interpreter is to compute, we say to evaluate, user input 
and MuPAD library functions. For this, both are first processed by the parser 
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which reads-in the commands given in the Mu PAD language and transforms 
them into the internal representation of Mu PAD objects. This representation 
is based on trees which are built up of nodes of the constructed C/C++ data 
type MTcell. Refer to section 4.4.1 for details. 

To compute a Mu PAD command means to evaluate such a tree recursively by 
visiting each node in preorder, substituting it with its derivation. The result of 
this process is a new tree which is transcribed into a user readable output and 
is displayed by the I/O system respectively the Mu PAD front end. 
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Figure 4.3: The MuPAD Interpreter 



The evaluator as well as all built-in functions operate on MuPAD objects such 
as various types of numbers, strings and high-level data structures such as lists, 
tables, polynomials, matrices etc. An overview over essential MuPAD data types 
and their internal representation is given in section 4.5. 

For constructing and manipulating MuPAD objects the memory management 
system MAMMUT is used. So, basic knowledge of it is required before starting 
to write module functions. The following section gives a brief introduction. 



4.4 Memory Management System 

The MuPAD memory management system MAMMUT [30] emulates a virtual 
shared memory machine and supports the programming of parallel algorithms 
using the PRAM model. All trees of the internal data representation of MuPAD 
objects are built up from nodes, so-called ce//s, of the constructed C/C++ data 
type MTcell. Such a cell is the smallest and atomic object of MAMMUT. 

4.4.1 Internal Data Type MTcell 

As shown in figure 4.4, each MuPAD cell (MTcell) consists of a so-called header^ 
a memory block and a point block. The point block is a list of pointers which 
refer to the children of the cell (node of a tree) whereas the memory block may 
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contain internal C/C++ data such as numbers -e.g. PARI numbers-, character 
strings -e.g. of MuPAD character strings or identifier- etc. 
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Figure 4.4: Structure of a MuPAD cell (MTcell) 



The header is used to control the cell within the virtual shared memory. It 
contains attributes for status information such as the signature (section 4.4.2) 
and the reference counter (section 4.4.3) which are described below. 

Usually, module programmers directly access only the point block of a cell 
when constructing or manipulating MuPAD objects. Basic routines available to 
directly operate on cells are described in section 6.6. Also refer to MFglobal. 



4.4.2 Signatures 

The signature is an integer number, a kind of check sum for MuPAD cells. It 
is used to speed up comparisons of MuPAD cells and trees and also defines an 
internal order of the MuPAD objects (see section 6.4.1). After constructing or 
manipulating MuPAD objects such as lists or expressions (refer to figure 4.6), 
the user has to make sure that the signature of the corresponding cell, and its 
parents, is recalculated using the routine MFsig. Otherwise two objects may 
not be noticed as equal even if they are. 



4.4.3 Reference Counter 

The reference counter is an integer number. Some data within the pool of 
MuPAD objects are stored as unique data} That is, they only exist once and 
there is no other object equal to it within the pool. To allow these objects to be 
used (referenced) more than once at a time, e.g. within different data structures 
or in form of multiple references as of identifier ’a’ in figure 4.5, a concept of 
reference counting is used. For every new reference to a cell, the corresponding 
reference counter is incremented by one. When a reference is removed since it 
is not needed any longer, the counter is decremented by one. 

In figure 4.5 the sub-expression ’a’ is referenced twice in the list, meaning that 
its reference counter was set to two. If ’6’ is to be replaced by a third reference 



^Examples of MuPAD objects which are stored as unique data are listed in section 6.7.1. 
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Figure 4.5: Unique Data Representation 



to ’a’, the user must make sure, that the reference counter of ’a’ is incremented 
by one. This is done using the routine MFcopy which creates a so-called logical 
copy of a MuPAD object. 

In contrast to MFcopy, the routine MFchange creates a so-called physical copy 
of a MuPAD object. This is done by allocating new memory and copying the 
contents of the object into the new memory space. This function is used only 
if an object is manipulated physically, e.g. when exchanging a sub-expression 
which means to exchange an entry of the point block, and any side-effects must 
be avoided. In any other case logical copies are preferred, because they do not 
occupy additional amount of memory and speed up comparisons. 

Note: Each copy and newly created MuPAD object must be destroyed by use of 
routine MFfree when it is not needed any longer. This is important since MuPAD 
performs no garbage collection during evaluation, but only after evaluation. 



4.4.4 C Memory Management 

In some cases the user might wish to allocate memory space independently from 
the MuPAD memory management system. This should be avoided, if possible. 
But if it is needed, instead of the C standard routines malloc and free the 
equivalent MuPAD routines MFcmalloc and MFcfree should be used. These 
routines can handle memory allocation and de-allocation on all platforms and 
operating systems supported by MuPAD. 

Detailed information about the MuPAD memory management system and its 
programming interface are given in the MuPAD Report MAMMUT [30]. 



4.5 Data Types 

This section introduces essential MuPAD data types and explains how they are 
supported by the MuPAD Application Programming Interface [MAPI). How- 
ever, it is also recommended to read the MuPAD User’s Manual [50] section 
2.3 Basic Types for additional information about MuPAD data types and their 
usage. 
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Table 4.1: MuPAD Kernel Data Types (basic domains) 



Data Type 


Creation 


Refer to 


Description 


D0M_FAIL 


MVfail 


4.5.1, 6.7.1 


object FAIL 


DOM-NIL 


MVnil 


4.5.1, 6.7.1 


object NIL 


DOM-NULL 


MVnull 


4.5.1, 6.7.1 


null (empty) object 


DOM-IDENT 


MFident 


4.5.2, 6.7.2 


identifier 


DOM-STRING 




MFstring 


4.5.2, 6.7.2 


character string 


DOM-BOOL 


MFbool, MFboolS 


4.5.3, 6.7.3 


2/3-state boolean 


DOM-APM 


MF, MFpari 


4.5.4 


integer |i| > 2^^ 


DOM-COMPLEX 


MFcomplex 


4.5.4, 6.7.4 


complex number 


DOM-FLOAT 


MFdouble 


4.5.4 


fp number (double) 


DOM-INT 


MFlong 


4.5.4 


integer |z| < 2^^ 


DOM-RAT 


MFrat 


4.5.4, 6.7.4 


rational 


DOM-ARRAY 


MFlist2array 


4.5.7, 6.7.11 


n-dim array 


DOM- POLY 


MFlist2poly 


4.5.7, 6.7.12 


polynomial 


DOM-EXPR 


MFnewExpr 


4.5.5, 6.7.6 


expression 


DOM- EXT 


MFnewExt 


4.5.5, 6.7.7 


domain element 


DOM-LIST 


MFnewList 


4.5.5, 6.7.5 


list 


DOM-DOM 


MFnewDomain 


4.5.6, 6.7.10 


domain 


DOM-SET 


MFnewSet 


4.5.6, 6.7.8 


finite set 


DOM-TABLE 


MFnewTable 


4.5.6, 6.7.9 


table 



On some systems the limit may be 2®^. Refer to MFisApm and MFisInt. 



4.5.1 Special MuPAD Objects 

The objects FAIL (DOM.FAIL), NIL (DOM.NIL) and nullO (DOM.NULL) are spe- 
cial to MuPAD and expected to be stored as unique data (section 4.4.3). Thus, 
they must not be physically copied. They are predefined by MAPI as the vari- 
ables MVfail, MVnil and MVnull (section 6.7.1) and can be used in form of 
logical copies. Refer to table 4.1 for additional type information. 



4.5.2 Strings and Identifiers 

Identifiers (D0M_IDENT) and character strings (DOM-STRING) are created from 
C/C-f+ character strings using the conversion routine MFident (respectively 
MFstring). Both are classified as character based data types, called the MAPI 
type MCchar, which can be used as an argument for the routine MFargCheck. 
The data type MCchar can also be checked using the routine MFisChar. Refer 
to table 4.1 for additional type information. 
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4.5.3 Booleans 

D0M_B00L provides a 3-state logic using the values TRUE, FALSE and UNKNOWN. 
These objects are expected to be stored as unique data (section 4.4.3) and thus 
must not be physically copied. They are predefined as the variables MVtrue, 
MVf alse and MVunknown (section 6.7.1) and can be used in form of logical copies. 

Conversion between Mu PAD Booleans and C/C++ Booleans can be done using 
the routines MFbool and MFboolS. Due to the fact that programmers mostly 
need a 2-state logic as usual in C/C++, MFbool converts the MuPAD value 
UNKNOWN into the C/C++ value false. If the user wishes to use a 3-state logic 
even on a C/C++ level, he/she explicitly has to use the routine MFboolS. Refer 
to table 4.1 for additional type information. 

4.5.4 Numbers 

MuPAD provides integer (D0M_INT) and floating-point (D0M_FL0AT) numbers, as 
well as rational (D0M_RAT) and complex (D0M_C0MPLEX) numbers for doing ar- 
bitrary precision arithmetic. For this, parts of the arbitrary precision arithmetic 
package PARI [4] are used inside MuPAD. 

In contrast to the MuPAD language, on the C/C++ level integer numbers are 
subdivided into D0M_INT and DOM.APM (arbitrary precision), depending on their 
size (refer to table 4.1). Both are classified as integers, called the MAPI type 
MCinteger, which can be used as an argument for the routine MFargCheck. The 
data type MCinteger can also be checked using the routine MFisInteger. 

Additionally, the types listed above are classified as numbers, called the MAPI 
type MCnumber, which can be used as an argument for the routine MFargCheck. 
The type MCnumber can also be checked using the routine MFisNumber. 

MAPI provides basic routines to convert MuPAD numbers into/from C/C++ 
numbers (section 6.5) and fast arithmetic on arbitrary precision numbers with 
a direct interface to the most relevant PARI routines (section 6.9). 

To convert MuPAD numbers into/from other arbitrary precision number rep- 
resentations, e.g. GMP^, the user must extract the PARI number from -and 
reembed it into- a MuPAD cell by use of routine MFpari (section 6.5.2) and 
directly convert the C/C++ representation of the PARI number. An example 
for this is given with the GMP interface described in section 10.4.1. 

On the other hand arbitrary precision number conversion can be done using the 
representation as a C/C++ character string as an intermediate format. This 
method is simple but slow and should be avoided, if possible. Refer to table 4.1 
for additional type information. 



^Gnu Multi Precision package, available on several sites via ftp, e.g. from suns it e. 
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4.5.5 Lists, Expressions and Domain Elements 

Lists (D0M_LIST), expressions (DOM.EXPR) and domain elements (D0M_EXT) are 
internally represented as a special kind of C/C++ vectors. Figure 4.6 shows 
their representation as trees built-up from MuPAD cells as well as the semantics 
of their operands, respectively elements (children). 
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Figure 4.6: Structure of Lists, Expressions and Domain Elements 



Lists, expressions and domain elements can be constructed and manipulated 
with the routines listed in section 6.7.5 Lists^ section 6.7.6 Expressions and sec- 
tion 6.7.7 Domain Elements. Refer to table 4.1 for additional type information. 



4.5.6 Sets, Tables and Domains 

Sets (D0M_SET), tables (D0M_TABLE) and domains (DOM.DOMAIN) are dynamic 
data structures implemented as associative lists (so-called hash tables^). 

Sets and tables can either be converted from/into MuPAD lists (DOM.LIST) or 
be constructed and manipulated with the routines listed in section 6.7.8 Sets 
and section 6.7.9 Tables. 

Domains (refer to domains [7]) can be constructed with the routines listed 
in section 6.7.10 Domains. Refer to section 2.3 to read about the domain 
representation of modules. Refer to table 4.1 for additional type information. 



4.5.7 Arrays and Polynomials 

The data type D0M_ARRAY represents n-dimensional arrays and is used as the 
basic data structure for the implementation of the MuPAD high-level domain 
Dorn: : Matrix which is used in the linear algebra package of MuPAD. Refer to 
the library documentation linalg [33] for detailed information about creating 
and using matrices in MuPAD. 

The data type D0M_P0LY is used to represent multi- variate polynomials over 
arbitrary rings and several monomial orderings. Refer to the library docu- 
mentation polynomials [11] for detailed information about creating and using 
polynomials in MuPAD. 



^The hash function uses the signature of a MuPAD cell for hashing. 
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Since directly constructing arrays and polynomials on a C/C++ level is some- 
what awkward, MAPI supports creating -respectively converting- them from 
MuPAD lists (D0M_LIST) which can be constructed very easily. Refer to section 
6.7.11 Arrays a,nd section 6.7.12 Polynomials as well as section 4.5.5 for detailed 
information. Refer to table 4.1 for additional type information. 



4.5.8 Other Data Types 

Besides the essential basic domains listed in table 4.1 MuPAD provides further 
data types: DOM_FUNC_ENV, D0M_EXEC, DOM.POINT, D0M_P0LYG0N, D0M_PR0C, 
and more. They are currently not fully supported by the MuPAD Application 
Programming Interface. For additional information about these data types refer 
to the MuPAD User’s Manual [50]. 

For examples on constructing and operating on objects of these kinds of data 
types refer to section 6.7.13. 



4.6 Displaying MuPAD Objects 

MuPAD is available for several computer platforms and operating systems with 
different window systems and different input and output concepts. To write 
portable modules, programmers must not use any input /output functions which 
are specific to the operating and/or window system. 

As an alternative MAPI provides the routine MFout for displaying MuPAD ob- 
jects and MFputs and MFprintf for displaying C/C++ data. The last ones 
behave similar to the C/C++ standard routines printf and puts. Read sec- 
tion 6.10.1 for detailed information about input and output in MuPAD. 



4.7 Module Mauageuieut Systeui 

The basic concept of dynamic modules as well as their usage was introduced in 
section section 1.2. Now, some technical information about the module manager 
and the linkage of dynamic modules is given. The complete technical description 
of this concept and its implementation in MuPAD 1.2.2 is available with the 
MuPAD Report Dynamische Module [40]. 

As MuPAD kernel functions, module functions are also written in the C/C++ 
programming language. They are compiled into a special kind of a dynamic 
library respectively shared library (machine code), which can dynamically be 
linked into the MuPAD kernel at run-time. Figure 4.7 shows a simplified scheme 
of the MuPAD module management system. 
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Figure 4.7: Scheme of the Module Management 

When loading a dynamic module, the dynamic library interface of the MuPAD 
kernel loads and links the module machine code file (figure 4.7 (a)). In cooper- 
ation with the module kernel interface^ module functions and their names are 
collected. They are registered by the module manager and propagated to the 
interpreter interface to make them public to the MuPAD interpreter and with 
this also to the user (refer to figure 4.8). 

The embedding of machine code of module functions into the MuPAD inter- 
preter is done in the same way as with built-in functions using the MuPAD data 
structures D0M_EXEC and DOM_FUNC_ENV^ 




Figure 4.8: Function Environment of a Module Function 
These data structures (figure 4.8) contain all information needed to jump into 
the machine code of the corresponding module function (figure 4.7, (b)): the 
key of the module manager service routine and the module name as well as the 
module function name. 

Furthermore, modules are organized in the same way as library packages by 
storing the module function environments in a domain. After this, the module 
functions are available to the user similar to library functions and can be used 
as usual (figure 4.7, (d)). The user sees no difference in using libraries and 
modules. Refer to section 2.3 for additional information. 

After linking a module, the kernel interface provides access to (nearly) all in- 
ternal MuPAD kernel objects (figure 4.7, (c)) and enables module programmers 

^Refer to the MuPAD User’s Manual [50], section 2.3.16 Function Environments, section 
2.3.17 Directly Executable Objects and the function built-in for detailed information. 
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to use internal routines and variables of the Mu PAD kernel. Kernel access can 
be established with different methods for address evaluation of kernel objects. 
They are discussed in section 4.7.3. Access to essential kernel routines and vari- 
ables is facilitated by the Mu PAD Application Programming Interface (MAPI). 

When loading a module, the module manager also looks for a file mod. mdg, 
with mod is the name of the module to be loaded. It may contain module 
procedures (section 7.2.1) as well as other (currently undocumented) objects 
which are read-in and bound to the module domain respectively the function 
environments of the module functions. Refer to function module: :load for 
additional information. 



4. 7,1 Dynamic, Static and Pseudo Modules 

Until now, only dynamic modules were discussed. In fact, the module manager 
distinguishes between three kinds of modules which differ slightly due to their 
linkage and their presence in main memory: dynamic-^ static-^ pseudo modules. 



4. 7. 1.1 Dynamic Modules 

Dynamic modules can be loaded and unloaded during a Mu PAD session, meaning 
their machine code is dynamically linked and unlinked. This is the default 
case and provides the highest degree of flexibility and an economical resource 
management. However, in some cases it is useful to declare a modules as static. 

4. 7. 1.2 Static Modules 

Static modules are linked dynamically at run-time exactly as dynamic modules 
but cannot be displaced automatically by the displacement and replacement 
strategies of the module manager. Only the user can unload static modules 
using the function module: : displace with the option Force. 

Static modules are needed if parts of the module machine code are called asyn- 
chronously by passing the module manager (figure 4.7, (b)), e.g. if an interrupt 
handler is defined in the module. Or, if the module stores any kind of state or 
status information that must not get lost, e.g. an open file handle or a pointer 
to dynamically allocated memory.^ Also refer to MFglobal. 

Dynamic modules can be declared as static either by setting the module gen- 
erator option -a static (section 5.4.1) when compiling the module source code 
or by declaring one of its module functions as static by use of the MAPI op- 
tion MCstatic (table 6.1). Additionally, the attribute static can be set and 
reset at run-time using the MAPI routine MFstatic. 



^When module code is unlinked from the kernel, all values of module variables get lost. 
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4. 7. 1.3 Pseudo Modules 

Pseudo modules consist of machine code that is statically linked when creating 
the MuPAD kernel. From the user’s point of view, pseudo modules provide the 
same functionality as static modules, but they cannot be unloaded in any way^. 

Pseudo modules may be used for special applications on those operating systems 
which do neither support dynamic linking nor related techniques. 



4.7.2 Displacement and Replacement Strategies 

The MuPAD interpreter interface and the module manager (figure 4.7) are com- 
pletely independent from each other. Based on the capability to unlink machine 
code of dynamic modules at any time during a MuPAD session, the module 
manager is allowed to unload the code of any dynamic module which is not cur- 
rently used. When the user calls a displaced function later, the module manager 
reloads the corresponding machine code automatically {load on demand) and 
transparently to the user. 

To provide an economical resource management when using dynamic modules, 
automatic displacement and replacement strategies were implemented within 
the module manager. At present, the following strategies are used: 

• Lack Of Memory: The memory management system as well as any kernel 
routine and module function can displace a module with respect to the 
method least recently used. Refer to the routine MFdisplace. 

• The Number Of Modules is limited to 256 simultaneously loaded modules. 
It can be restricted further using the function module: :max. If this limit 
is reached, new modules replace older modules with respect to the method 
least recently used. 

• Aging: With the function module: :age the user can define a maximum 
age (specified in seconds) for dynamic modules. Modules age if they are 
not used, i.e. the age rises in periods where none of their module functions 
are called. If the age of a module reaches the maximum age, its machine 
code is displaced automatically. Calling a module function or reloading a 
module resets the age of the corresponding module to zero. 

Note: Displacement and replacement strategies do not effect static and pseudo 
modules because their machine code cannot be unloaded during a session. 



^Option Force of function module: : displace does not effect pseudo modules. 
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4.7.3 Address Evaluation for Kernel Objects 

The technical realization of dynamic modules is based on the concept of dynam- 
ically linked libraries respectively shared libraries. Since some operating systems 
do not fully support dynamic linking of these kinds of libraries as needed for the 
concept of dynamic modules, extended methods for internal address evaluation 
of kernel objects were implemented. The critical point is, that some dynamic 
linkers do not automatically provide full access to the Mu PAD kernel code for 
modules which are dynamically linked at run-time. 

Figure 4.9 shows a simplified scheme of the extended address evaluation. Al- 
though this method looks somewhat awkward, in practice it is as fast as using 
the linkage provided by the C+-h compiler and linker. 



Kernel 




Module 


1. Phase 

Determine address . 
of specified object 


Send object — 

specifier 

Return object 
address 


Ask for object address 
Cast address to 


2. Phase 
Using kernel code - 




appropriate type 

Access kernel routine 
respectively variable 









Figure 4.9: Accessing MuPAD Kernel Objects from a Module 



The extended methods are compatible on all platforms and operating systems 
supported by MuPAD. Furthermore, they support linking of dynamic modules 
that have been compiled by some C+4- compilers different from and incom- 
patible with the one used by the developers for compiling the MuPAD kernel.^ 
They are hence chosen as the default method for address evaluation of kernel 
objects within modules. 

Creating a module with the module generator, the user can optionally choose 
between three kinds of address evaluation of kernel objects (section 5.4.1): 

• f unc: (default) Address evaluation is done by a function call. Tracing of 
kernel entries is possible.^ 

• table: Address evaluation is done by directly reading-out a kernel address 
table. Module tracing cannot be supported here. Although this method is 

^For example, the CC available with Solaris 2.5 and the GNU g-t-4- 2.7.2 use different 
naming conventions for function and variable names in the symbol tables of machine code 
object files. Problems like this are well known in the context of software development using 
a heterogeneous compiler environment. 

® Refer to Pref : : ModuleTrace( ) . This feature is suitable for kernel developers only. 
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faster than the method func, in practice there seems to be no significant 
difference in the efficience of all three methods.^ 

• link: Address evaluation is done by the operating system in combination 
with the C++ compiler and the dynamic linker. 

Additional information about compiling and linking of modules are given with 
the description of the module generator in chapter 5. 



^This statement may not be true with future versions or ports of the module manager for 
other operating systems and compilers. Therefore this option is offered to the user. 




5. Module Generator 



This chapter describes the concept and the usage of the module generator (mmg), 
emphasizing UNIX operating systems^ Essential options and keywords for con- 
trolling module creation and specifying module characteristics are introduced. 

The module generator compiles and links module source code into an executable 
module (figure 5.1). While analyzing a source file xx mmg creates a temporary 
file . C which contains code extensions needed for the module management. 

Furthermore, a file xx .mdg may be created which contains Mu PAD objects used 
by the module. MMGa^a: .C, including the user’s source code, is then compiled into 
an object code file xx .0 and finally linked to the module file xx .mdm. This can 
be loaded within MuPAD instantly by using the command mod\ile(xx) . 



C*«.c3 



^ 

> ' ' Creation: 



^Analysis: 



Options 

I 

Functioruy Options,,.. 



. j C++ Code Extensiaos 

CmMGxx.c)^ ... i-fMAPl) 

y^/ Cnmpdmp: CC acc. g++„„ 



Linking: td, CC, xic, acc, g++..^^ " ^ 





CLifamries) 



Figure 5.1: Scheme of the MuPAD Module Generator 



The module generator must at least be given the name of the module source 
file to be processed. This file is called the module main source file. 

If the module source code is split into several source files then refer to section 
5.2.3 for information on compiling these files. However, all module inline options 

^ Users of Windows 95/NT and Apple Macintosh PowerPC systems should refer to section 
8. Creating dynamic modules differs slightly for these systems. 
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(section 5.1.1) as well as all module functions (section 5.1.2) must be defined 
within the module main source file. 

The executable dynamic module as well as all temporary files are placed in the 
current working directory, respectively in a directory specified by the user. 



5.1 Analysis and Code Extension 

5.1.1 Inline Options 

mmg starts the analysis of the user source code by looking for so-called inline 
option. They can be inserted as expressions of the form 

MMG( <system^> option = ’’value^’ ) 

where value is a character string containing mmg command line options as used 
on UNIX operating systems and option is one of the names listed in table 5.1. 

Inline options are used to set module generator options. They overwrite com- 
mand line options and must be placed in the module main source file before 
any definition of module functions. Inline option are ignored if they are nested 
within C/C+-f comments. 

Table 5.1 lists all inline options currently available and their corresponding mmg 
command line aliases as used on UNIX operating systems. For details about 
these options and their parameters refer to section 5.4 and appendix C. 



Table 5.1: Inline Options 



Inline Option 


mmg Option 


compiler 


option -CC 


linker 


option -LD 


linkage 


— option -j 


info 


option -V 



of the Module Generator 



Inline Option 


mmg Option 


coption 


— option -oc 


loption 


— option “ 0 l 


attribute 


-> option -a 


prefix 


-> reserved 



If system is specified within an inline option, this option is activated only if the 
module source code is compiled on the corresponding operating system. Table 
5.2^ lists the system aliases used by Mu PAD. The Mu PAD alias for the current 
operating system can be determined either by executing mmg -sys or by typing 
the Mu PAD command sysname(Arch); within a Mu PAD session. 



^As new ports of Mu PAD may become available, this table may be incomplete. 
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Table 5.2: Operating System Aliases used by MuPAD 



system 


Operating System 


i386 


PC/AT Linux 2 


sun4 


Sun, SunOS 4 


Solaris 


Sun, Solaris 2 


sgi5 


Sgi, IRIX 5/6 


ibmrsGOOO 


RS6000, AIX 3/4 


openbsd 


PC/AT OpenBSD 2 


freebsd 


PC/AT FreeBSD 2 



system 


Operating System 


netbsd 


PC/AT NetBSD 2 


mklinux 


Mac68k, Linux 2 


hp 


HP, HP-UX 9/10 


windows 


PC/AT, Win.95/NT 


macintosh 


MacPPC, Sys. 7 


alpha 


DECalpha, OSFl 


alinux 


DECalpha, Linux 



5.1.2 Module Functions 

After interpreting the inline options, mmg registers the module functions defined 
by the user by looking for expressions of the following form: 

MFUNC ( name , option ) { body } MFEND 

All module functions must be defined using this syntax - refer to section 6.2 
for a detailed explanation. After analyzing the module main source file, the 
extended module source code file MMG name. C is generated and compiled and 
linked as described in the following sections. 



5.1.3 Module Procedures and Expressions 

While looking for module functions (section 5.1.2), the module generator also 
accepts definitions of so-called module procedures and module expressions^ in- 
cluded into the module source code using the following syntax: 

MPR0C( name = ) respectively MEXPR( name = ) 

They are written into the file name .mdg to be inserted into the module domain 
when the corresponding module is loaded. Refer to section 7.2 for details. 



5.2 Creating Executable Modules 

5.2.1 Compiling 



The extended module source file MMGname .C is compiled to the module object 
file name . o (refer to figure 5.1). In general, the module generator uses either the 
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operating system’s default C++ compiler (e.g. CC, xlC, cxx, acc) or the GNU 
g++ for this. The syntax of the compiler call is displayed during compilation 
when the mmg option -v is set. 

However, the compiler can be changed using the inline option compiler (see 
table 5.1), the mmg command line option -CC (section 5.4.3) or by defining the 
environment variable MMG_CC (appendix C). 

Changing the compiler requires the user to know how to instruct the new com- 
piler to create code for shared respectively dynamic libraries. These options 
strongly depend on the operating system as well as on the specific compiler it- 
self. For example, -LD ^CC -pic -G^ respectively -LD ^xlC -+^ must be used 
to instruct mmg to use the default compiler on a Solaris respectively ibmrsSOOO 
operating system. 

Note: On most UNIX operating systems, dynamic modules and all libraries 
that are linked to them must be compiled as Position Independent Code [PIC). 
Most compilers can be instructed to compile PIC code using the option -pic, 
-PIC or -f pic^. If you are not sure how to directly compile libraries which are 
to be linked into dynamic modules then use mmg in combination with option -c 
instead of directly using a C/C++ compiler. Also refer to section 5.2.3. 

5,2.2 Linking 

The module object file name . o is linked to a special kind of a shared library file 
name .mdm (see figure 5.1). In general the module generator uses the operating 
system’s default linker Id directly or indirectly by use of one of the compilers 
listed in section 5.2.1 for this. Further object code files and libraries can be 
linked using the mmg options -ol file and -llib. The syntax of the linker call is 
displayed during linking when the mmg option -v is set. 

However, the linker can be changed either using the inline option linker (table 
5.1), the mmg command line option -LD (section 5.4.3) or by defining the envir- 
onment variable MMG_LD (appendix C). 

Changing the linker requires the user to know how to instruct the new linker or 
compiler to link shared respectively dynamic libraries. These options strongly 
depend on the operating system as well as on the specific linker/ compiler itself. 
For example, -LD ^CC -pic -G -1C ^ respectively -LD ^xlC -bM:SRE -e 
must be used to instruct mmg to use the default linker/compiler on a Solaris 
respectively ibmrsGOOO operating system. 

^This syntax is used by the GNU compiler g++. 

^The token */,E is an internal alias for the so-called entry point of the dynamic module. Some 
operating systems respectively linkers need this information to create dynamic libraries. 
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5.2.3 Splitting Module Sources 

Module source code may consist of several C/C++ files which can be compiled 
seperately. Using mmg for this, except for the module main source file (page 43), 
the option -c main=name must be set, where name is the name of the module 
main source file without the suffix. Source files which do not use any Mu PAD 
kernel routines or variables can be compiled directly using a C++ compiler. 

Note: All module source files should be compiled with the same compiler to 
avoid conflicts due to compiler incompatibilities. Files which are compiled by 
directly using a C++ compiler must be compiled to PIC code (see page 46). 

The main source file itself must be compiled by mmg as usual while linking the 
corresponding module object code files. Object code files are linked using the 
option -ol file. Additional system and user libraries can be linked using the 
option -llib. Also refer to section 5.4.3. An example that demonstrates the 
creation of a module consisting of several source files is given in section 10.1.2. 



5.3 Module Debugging 

Dynamic modules can be debugged with a usual C/C++ source level debugger. 
For this, the module generator must be instructed to include debug information 
into the module binary and not to remove temporarily created source (MMG* .C) 
and object (*.o) files (refer to section 5.4.2). A detailed introduction into 
debugging dynamic modules is given in section 8.7. 



5.4 Module Generator Options 

The module generator provides options to set module properties, to control 
module creation as well as to control compiling and linking modules. A complete 
summary of all options is given in appendix C. 



5.4.1 Module Properties 

The following options specify important characteristics of the compiled module. 
-V text: 

Instructs the module generator to insert the character string text as user 
information into the module. It is displayed when the function info is 
applied to this module. 
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-a static: 

Declares a dynamic module as static to prevent the module manager 
from displacing the module machine code automatically. This option must 
be used if the dynamic module contains an interrupt handler or stores 
a state or status information like an open file handle or a pointer to 
dynamically allocated memory space which must not get lost. Also refer 
to the function attribute MCstatic (table 6.1, page 56). 

- j [f unc I table I link] : 

Specifies the kind of address evaluation for Mu PAD kernel objects that is to 
be used by the module. Refer to section 4.7.3 for additional information. 

5.4,2 Module Creation 

The following options control administrative features of the module generator. 
Compiler and linker options are described in the following section. 

“C main=name: 

Instructs the module generator to compile the given source file to an object 
file which can be linked into the module main source file name.C. The 
given source file must not contain any inline options or module functions. 
Refer to section 5.2.3 for details. 

-g' 

Instructs the module generator to include debugging information into the 
module binary and prevents it from removing temporarily created files. 

-nog, -noc, -nol, -nor: 

Instructs the module generator to skip the generation of the module man- 
agement code, the compiler or linker phase, respectively prevents mmg from 
removing temporarily created files. 

-op path: 

Instructs the module generator to place all newly created files into the 
directory path. By default, the current working directory is used. 



-sys: 

Instructs the module generator to display the alias used by Mu PAD for 
the current operating system. Also refer to section 5.1.1. 



Instructs the module generator to log all actions that are carried out 
during module creation. 
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5.4.3 Compiler and Linker 

The following mmg options passes compiler and linker options through the mod- 
ule generator to the corresponding tools. 

-CC cccally -LD Idcall: 

Instructs the module generator to use the compiler cccall respectively the 
linker call Idcall to compile and link the module source code. Also refer 
to section 5.2.1 and 5.2.2. 

-gnu: 

Instructs the module generator to use the GNU compiler g++ instead of 
the system’s default compiler and linker.^ 

-nognu: 

Instructs the module generator to use the system’s default compiler and 
linker instead of the GNU compiler g++.^ 

-oc copt y -ol lopt: 

Instructs the module generator to pass option copt to the compiler and 
option lopt to the linker. If an option contains any whitespace characters 
(space, tab, linefeed, . . .), it must to be quoted. 

-Dname y -Ipath; -Lpath y -llib: 

These options are directly passed to the compiler respectively the linker. 



5.5 Warning and Error Messages 

The module generator may display the following warnings and error messages 
while analyzing the user’s module source file. Other messages which may be 
displayed by mmg are intended to be self-explanatory. 

Source name needs a suffix: 

Error, mmg expects that the name of the source file contains the suffix .( 7 , 
cxx^ .CPP or .c which is needed by most C/C-f-h compilers. 

Multiple source files defined: 

Error, mmg only accepts one source file. If the module is split into several 
source files, option -c (section 5.2.3) should be used to compile these 
source files except the module main source file. 

^It is recommended to use the GNU compiler release g-f-h 2.7.2 or a newer. 

^Depending on the operating system, the compiler and linker used by mmg by default to 
create modules is set to the one that was used for compiling the Mu PAD kernel. 
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Module options are not allowed in this file: 

Error. Source files which are compiled by use of option -c (section 5.2.3) 
must not contain any inline options (section 5.1.1). Move all inline options 
into the module main source file. 

Options must be defined before any function: 

Error. Move the inline option (section 5.1.1) to the top of the source file. 

Unknown option: 

Error, mmg scanned an invalid inline option (section 5.1.1). Correct the 
misspelling. 

Source overwrites option ^xxx^: 

Warning. The user has set the mmg command line option xxx which was 
overwritten by an inline option (section 5.1.1) of the current source file. 

Multiple defined module function 

Error. Two or more module functions have the same name. Rename these 
functions. Also refer to section 3.3 for reserved function names. 

MFEND misses matching MFUNC(): 

Error. Any non-module function was terminated with an MFEND tag. 

Invalid module function attribute: 

Error, mmg scanned an invalid function attribute (table 6.1). Correct the 
misspelling. 

Missing MFEND for function MFUNC(...: 

Error. The body of a module function must be terminated with the 
keyword MFEND. 

Procedure/Expression string expected in ^MPROC^ or ^MEXPR^: 

Error. Module procedures respectively expressions must be included as 
C/C-f+ character strings. 

Missing xxx . . .: 

Error. Token xxx was expected and must be inserted at or before the 
given position.^ 

. . . xxx expected . . .: 

Error. Token xxx is missed and must be inserted at the given position. 

^mmg may not be able to determine the exact error position because it does not analyze 
the C/C-[-f code within the body of module functions. In any case, the error occurred in or 
before the line number displayed with the error message. 
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Too many xxx: 

Error. Token xxx is either a right ’}’ -brace- or ’)’ -parentheses- for which 
no corresponding left brace respectively ’(’ was scanned before.^ 

Unterminated string or character constant: 

Error. A character constant has not been terminated by ” or ’. Insert the 
corresponding terminator at or before the given position.^ 

Unterminated ANSI-C comment: 

Error. An ANSI-C comment was not terminated with the character */. 
Insert the terminator at or before the given position.^ 

BAD RELEASE OF MuPAD KERNEL- INCLUDES: 

Error. The release number of the MuPAD kernel header files {MAPI inter- 
face) is different from that of the module generator. You might have mixed 
the installation of two different MuPAD versions. Make sure that mupad 
and mmg (installed in $MuPAD_ROOT_PATH/$ARCH/bin) and the Mu PAD 
header files (installed in $MuPAD_ROOT_PATH/share/mmg/include) belong 
to the same Mu PAD release. 

Warning: Module ^xxx^ was created for R-x.z.y...: 

Warning. This warning may be displayed by a module when it is loaded 
into the Mu PAD kernel. The module was compiled with a module gen- 
erator which release number is different from that of the current Mu PAD 
kernel. The module may not work properly and may also crash the Mu PAD 
kernel. Just recompile it with the corresponding module generator. 



®mmg checks the source for matching braces because the MAPI keyword MFUNC -as well as 
several others- is defined as a C/C-f-f macro for which reason missing braces may result in 
obscure error messages of the C-f-f compiler. 




6. Application Programming 
Interface (MAPI) 



This chapter describes the MuPAD Application Programming Interface (MAPI) 
and lists the routines and variables currently available, giving examples (at the 
end of each section) on how to use them. This chapter is intended to be used 
as a reference manual and follows the idea of learning-by-doing. 



6.1 Introduction and Conventions 

MAPI is the user’s C/C++ interface to the MuPAD kernel.^ The fact that main 
parts of the MuPAD kernel are implemented in ANSI-C is reflected by MAPI. 
At present, it uses only basic features of the C++ programming language. 



6.1.1 Naming Conventions 

MAPI consists of data type definitions (MT. . .) for internal MuPAD data types, 
definements (MD. . .) for internal usage only, constants (MC. . .) to control the be- 
haviour of MAPI routines and module functions, variables (MV. . .) for predefined 
MuPAD objects and essential properties of module functions as well as C/C++ 
(inline) routines (MF. . .) interfacing internal methods of the MuPAD kernel. 

Note: The identifier prefixes listed in parentheses above are reserved for MuPAD 
and MAPI and should not be used to define or declare any user objects. 
Moreover, in general all identifier prefixes M followed by one, two or three capital 
letters should not be used for declarations in order to avoid naming conflicts 
with internal objects of the MuPAD kernel. If naming conflicts occur then refer 
to section 9.1 to read about work arounds. 



^On UNIX systems MAPI can also be used with the MuPAD C-caller version MuLib. 
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6.1.2 Documentation Style 

The MAPI objects described in this chapter are subdivided into several cate- 
gories according to the different aspects of module programming. A complete 
lexicographic index of all MAPI objects, also subdivided according to these 
categories, is given in appendix D. 

Each section starts with some general information about the current topic and 
references to related sections, followed by a list of descriptions of the routines, 
variables, constants and data types available in this category of MAPI defini- 
tions. At the end of each section (respectively subsection) examples are given. 

Note: In general MAPI routines are characterized as listed below. If a routine 
does not follow one of these rules, the deviation from the standard behaviour is 
explicitly mentioned with its description. 

• Mu PAD objects returned by MAPI routines are newly created or logical 
copies of existing objects. This means they must be freed by use of MFf ree 
when they are no longer needed. 

• Mu PAD objects passed to MAPI routines are neither changed nor auto- 
matically freed by this routine. 



In this chapter MAPI objects are described using the following format: 



< object name> A brief one line long description 

■ <type of return value> <object name> ( < parameters if necessary > ) 
This section contains a detailed description of the object <object name>. It de- 
scribes its functionality and may also contain references to related routines and vari- 
ables. Important notes are emphasized in this way. 



6.1.3 Examples 

The examples given in this chapter can directly be tested in combination with 
Mu PAD release 1.4 and the hypertext version of this book. Just click on the 
label >> to compile the displayed C/C-f+ source code into a dynamic module 
and to execute the corresponding commands within your Mu PAD session. 

Note: Before these examples can be used interactively, first the software from 
the accompanying CD-COM must be installed respectively configured. Refer to 
appendix A for details about installing and configuring Mu PAD and the online 
examples and module applications. The appendix also describes how to start 
and read the online hypertext version of this book. 
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• Click on >> to copy the example to the corresponding Mu PAD session window. 
There it can be executed (and possibly changed). The function runit simply 
returns the Mu PAD identifier hello. 



» read("Makemod")("exa060100a") : 

// The MuPAD command above compiles and executes this example. 
// Below, the complete C/C++ source code of the module with its 
// module functions and subroutines is listed. 

MFUNC( runit, MCnop ) // the function ’runit’ 

{ MFreturnC MFident ("hello”) ); // returns an identifier 

} MFEND 

// Click on ’»’ below to execute the displayed commands again 

» runit 0; # MuPAD input : demonstrates the usage of the module # 
hello # MuPAD output: displays results of module functions # 



More sophisticated examples and module applications are given in section 10. 



6.2 Defining Module Functions 

Module functions are defined using the following syntax (see section 5.1.2): 



MFUNC ( name , option ) { body } MFEND 

Here, name is a C/C++ identifier defining the module function name as visible 
in MuPAD. option is either one of the constants listed in table 6.1 or a sequence 
of them, concatenated by the operator {binary or), body is the module 
function body containing usual C/C++ code with two exceptions: accessing 
the arguments of a module function and leaving a module function is special. 

Also refer to section 3.3 for information about predefined domain methods and 
reserved names of module domains. Refer to section 7.2.1 on how to define 
module procedures and module expressions. 

The following options are available to control the behaviour of module functions. 
Refer to section 6.10.4.3 for detailed information. 



6.2.1 Accessing Module Function Arguments 

When a module function is called, its function arguments are passed in form 
of an expression (D0M_EXPR, see section 4.5.5) in which the 0th operand con- 
tains the function environment (D0M_FUNC_ENV, see section 4.7) of this module 
function and the operands 1 to n contain the function arguments. 
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Table 6.1: Module Function Attributes 



Option 


Description 


MChidden 


The function is not listed in the module interface. 
Nevertheless, it can be directly called by the user. 


MChold 


Option hold as known from procedures. 


MCnop 


no option, the function behaves like a procedure. 


MCremember 


Option remember as known from procedures. 


MCstatic 


This code is not displaced automatically. 



Before the body of the function is entered, the arguments are pre-processed 
and -if option MChold is not set- evaluated. The evaluated arguments are then 
stored in a local variable named MVargs and MVnargs is set to the new number 
of evaluated arguments. This number may differ from the number of arguments 
passed to the function because Mu PAD flattens^ expression sequences. For ex- 
ample, during evaluation the function call f (1, (2. 1,2.2) ,3) is flattened to 
f(l,2.1,2.2,3)) and the number of arguments increases from 3 to 4. 

Note: To access and check the arguments of a module function the following 
routines and variables are provided. They must only be used directly within 
the body of a module function but cannot be used within subroutines. 



MFarg Returns the n-th function argument 

■ MTcell MFarg ( long n ) 

MFarg returns the n-th argument passed to the module function. This argument is 
not copied by MFarg. 



MFargCheck Checks the type of the n-th function argument 

■ void MFargCheck ( long n, long dom ) 

MFargCheck aborts the current evaluation with the error message Invalid argument if 

the n-th argument is not of type dom. dom must be either a basic domain (DOM , 

refer to table 4.1) or one of the meta types MCchar, MCinteger and MCnumber (section 
6.10.4.2). Read section 4.5 for additional information about MuPAD data types and 
section 6.3 for details about extended type checking. 



^Also refer to the MuPAD User’s Manual [50, p. 33]. 
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MFnargsCheck Checks the number of function arguments 

■ void MFnargsCheck ( long n ) 

MFnargsCheck aborts the current evaluation with the error message Wrong number 
of arguments if MVnargs is not equal to n. 



MFnargsCheckRange Checks the number of function arguments 

■ void MFnargsCheckRange ( long min, long max ) 

MFnargsCheckRange aborts the current evaluation with the error message Wrong 
number of arguments if MVnargs is not in range min. . .max. 



MVargS Sequence of function arguments 

■ MTcell MVargS 

MVargS contains the arguments passed to the module function. MFarg allows to access 
specific arguments. Refer to page 56 to read about flattening of function arguments. 



MVnargs Number of function arguments 

■ long MVnargs 

MVnargs contains the number of arguments passed to the module function. Also refer 
to the variable MVargs and the routine MFarg 



6.2.2 Leaving Module Functions 

There are exactly two correct ways to leave a module function. The first one is 
to return a result with MFreturn which behaves similarly to the built-in function 
return. The second one is to abort the module function with an error message 
using the routine MF error which behaves like the built-in function error. 

Note: Whereas MFerror may be used in any subroutine executed by a module 
function, MFreturn may only be used directly within the body of a module 
function. Before leaving a module function, all temporarily created objects 
that are no longer needed must be freed using the routine MFfree (section 6.6). 



MFerror Aborts a module function with an error message 

■ void MFerror ( char* mesg ) 

MFerror aborts the current evaluation with the error message mesg. It behaves sim- 
ilarly to the built-in function error. 
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MFreturn Returns the result of a module function 

■ MTcell MFreturn ( MTcell result ) 

MFreturn returns the result of a module function. It behaves similarly to the built-in 
function return. Note that result must be either a newly created object or a logical 
respectively physical copy of an object. MFreturn must not return the empty 
object MCnull. MFreturn does not copy its arguments. 



Examples 

• The module function inc adds 1 to the number passed as function argument. 



» read ( "Makemod" ) ( "exa060200a" ) : 




MFUNC( inc, MCnop ) 


// function ’inc\ no option 


{ MTcell number; 


// declares a MuPAD variable 


MFnargsCheckC 1 ); 


// one argument is expected 


MFargCheckC 1, MCnumber ); 


// this must be any number 


number = MFadd( MFarg(l), MVone ) 


// adds to the number 


MFreturn ( number ) ; 


// returns the result 


} MFEND 


// end of the function ’inc^ 


» inc(13/42); 




56/42 





• The function memo remembers all results it computed before and thus does not 
need to re-compute them, i.e. the function body need not be executed again. 
This is the easiest way to speed up often called module functions. 



» read ( "Makemod" ) ( "exa060200b" ) : 




MFUNC( memo, MCremember ) 


// function with a memory 


{ MFnargsCheckRangeC 1, 2 ); 


// one or two arguments 


MFargCheckC 1, D0M_IDENT ); 


// first must be identifier 


MFputs("Can’t remember"); 


// displays a message 


MFreturnC MFident ("Ok") ); 
} MFEND 


// returns identifier ’Ok’ 


» memo (tom), memo (tom); 




Can’t remember 
Ok, Ok 





• The following functions return the number of arguments they receive. Whereas 
count 1 evaluates its arguments as usual, in function count 2 the option hold 
suppresses the evaluation and flattening of the function arguments. 
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» readC’Makemod") ("exa060200c") : 




MFUNC( count 1, MCnop ) 


// using no sepcial option 


{ if (IMVnargs) MFerror( "No args" ) 


; // exit with error message 


MFreturnC MFlong(MVnargs) ); 
} MFEND 


// returns the num. of arg. 


MFUNC( count2, MChold ) 


// using the option ^hold’ 


{ if (IMVnargs) MFerror( "No args" ) 


; // exit with error message 


MFreturn( MFlong(MVnargs) ); 
} MFEND 


// returns the num. of arg. 


» countK 1,(0»0),2 ) <> count2( 1,(0»0),2 ); 
4 0 3 



6.3 Type Checking 

Type checking of Mu PAD objects is divided into two main categories: fast check- 
ing of basic domains and more sophisticated checking of high-level domains and 
constructed data types. On the C/C-(-+ language level the same type names 
are used as in the Mu PAD programming language. Additionally, the meta types 
MCchar, MCinteger and MCnumber were introduced (section 6.10.4.2). 



6.3.1 Basic Domains and Expressions 

Basic type checking can be done very efficiently using either MFdom to determine 
-and maybe store- the basic type of a Mu PAD object (the so-called basic do- 
main) or using a member of the family of MFis. . . routines which is often more 
convenient and also allows to identify special Mu PAD objects like the Boolean 
constants, etc. Also refer to MFargCheck. 

The basic domain D0M_EXPR (figure 4.6) is special because its elements are 
subdivided into so-called expression types according to their 0-th operand. Thus 
MFisExpr accepts an optional second argument to specify the specific expression 
type to check for. 

Similarly to expressions, domain elements (D0M_EXT, figure 4.6) are subdivided 
into so-called domain types according to their 0-th operand. Thus MFisExt 
accepts an optional argument to specify the specific domain type to check for. 



MFdoni Returns the basic domain of an object 

■ long MFdom ( MTcell object ) 

MFdom returns the basic domain of object. This is represented by a C/C-1-+ integer 
constant D0M_. . . (refer to table 4.1), whose name is equal to that known from the 
Mu PAD programming language. 
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MFis Checks for a specific basic domain or a special object 

■ MTbool MFis. . . ( MTcell object ) 

MFis . . . defines a family of routines. For each basic domain D0M_XXX (refer to table 
4.1) a routine MFisXxx is available to check if the argument object is of this type. For 
example MFisBool returns true if object is of type D0M_B00L and false otherwise. 

Additional routines for identifying special MuPAD objects are available: MFisFail, 
MFisNil, MFisNull, MFisFalse, MFisTrue, MFisUnknown, MFisHalf , MFisI, MFisOne, 
MFisOne_, MFisTwo, MFisTwo_, MFisZero. Also refer to section 6.7.1. 



MFisApm Checks for arbitrary precision integer numbers 

■ MTbool MFisApm ( MTcell object ) 

MFisApm returns true if object is an integer number greater or equal to 2^^ (or < 
-2^^).^ Otherwise it returns false. Also refer to MFisInt and read section 4.5.4. 



MFis Char Checks for character based basic domains 

■ MTbool MFisChar ( MTcell object, char* text=NULL ) 

MFisChar returns true if one of the routines MFisIdent or MFisString returns true. 
Otherwise it returns false. MFisChar accepts an optional argument text to specify 
the identifier (respectively the character string) to check for. 



MFisExpr Checks for expressions 

■ MTbool MFisExpr ( MTcell object, char* fun ) 

In addition to the description given in MFis. . ., MFisExpr accepts an optional argu- 
ment fun to specify the expression type to check for. If object is an expression and 
its 0-th operand is the identifier fun then MFisExpr returns true, otherwise false. 

■ MTbool MFisExpr ( MTcell object, long fun ) 

In contrast to the routine described above, here the expression type is specified by one 
of the integer constants defined in section Definition der L ’ - Systemfunktionen of the 
header file $MuPAD_ROOT_PATH/share/mmg/include/kernel/MUP_constants .h. 



MFisExt Checks for domain elements 

■ MTbool MFisExt ( MTcell object, MTcell domain ) 

In addition to the description given in MFis. . ., MFisExt accepts an optional argument 
domain to specify the domain type to check for. If object is an element of domain 
then MFisExt returns true. Otherwise it returns false. 

^ For 64bit versions of MuPAD, e.g. on DECalpha/OSF, the limit is 2^^. This limit depends 
on sizeof (long) and the implementation of the underlying arithmetic package PARI [4]. 
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MFisIdent Checks for identifiers 

■ MTbool MFisIdent ( MTcell object^ char* text=NULL ) 

In addition to the description given in MFis. . MFisIdent accepts an optional argu- 
ment text to specify the name of the identifier to check for. 



MFisInt Checks for machine integer numbers 

■ MTbool MFisInt ( MTcell object ) 

MFisInt returns true if object is an integer number between —2^^ and Other- 
wise it returns false. Also refer to MFisApm and read section 4.5.4. 



MFis Integer Checks for integer numbers 

■ MTbool MFisInteger ( MTcell object ) 

MFisInteger returns true if one of the routines MFisApm or MFisInt returns true. 
Otherwise it returns false. 



MFisNumber Checks for numbers 

■ MTbool MFisNumber ( MTcell object ) 

MFisNumber returns true if MFisComplex, MFisFloat, MFisInteger or MFisRat re- 
turns true. Otherwise it returns false. 



MFis St ring Checks for character strings 

■ MTbool MFisString ( MTcell object^ char* text=NULL ) 

In addtion to the description given in MFis. . ., MFisString accepts an optional argu- 
ment text to specify the character string to check for. 



6.3.2 Domains and Constructed Data Types 

Domain elements (D0M_EXT, figure 4.6) as well as constructed data types, e.g. 
a list of integers, can be analyzed using the built-in functions domtype, type and 
testtype interfaced by the MAPI routines MFdomtype, MFtype and MFtesttype. 
Refer to the MuPAD User^s Manual [50] for detailed information. 



MFdomtype Returns the basic domain of an object 

■ MTcell MFdomtype ( MTcell object ) 

MFdomtype behaves exactly like the built-in function domtype. 
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MFtype Returns the type of an object 

■ MTcell MFtype ( MTcell object ) 

MFtype behaves exactly like the built-in function type. 



MFtesttype Checks for specific types or data structures 

■ MTbool MFtesttype ( MTcell object, MTcell type ) 

MFtesttype behaves like the MuPAD built-in function testtype but returns a C/C++ 
Boolean constant of type MTbool instead of a MuPAD object of type MTcell. 



Examples 

t The function checkit demonstrates basic type checking for MuPAD objects. 



» read ( "Makemod" ) ( "exa060300a" ) : 
MFUNC( checkit, MCnop ) 




// ^ checkit^ 


{ MFnargsCheck(l) ; 




// get first 


MTcell a=MFarg(l); 




// argument 


if( MFisNumber(a) ) MFputs( 


"Number" ) ; 


// a==number? 


if( MFdom(a)==DOM_RAT ) MFputs( 


"Rational" ); 


// a==rational? 


if( MFisExpr(a, "sin") ) MFputs( 


"Sin function" ) 


; // a==sin(*)? 


if( MFisTrue(a) ) MFputs( 


"True" ); 


// a==TRUE? 


MFreturnC MFdomtype(a) ); 




// domtype(a) 


} MFEND 

» checkit (1/3) ; 

Number 

Rational 

DOM.RAT 







• listofiC object) returns TRUE if object is a list of integers and otherwise 
FALSE. This kind of type checking is time consuming and should be avoided if 
possible. MF constructs objects from C/C++ character strings, see p. 69. 



» read("Makeniod")("exa060300b") : 




MFUNC( listofi, MCnop ) 


// 'listofi^ 


{ MFnargsCheck(l) ; 


// one argument? 


MTcell type=MF ( "Type : : ListOf (D0M_INT) " ) ; 


// build expression 


MTbool isok=MFtesttype( MFarg(l), type ); 


// call testtype 


MFfreeC type ); 


// free expression 


MFreturnC MFbool(isok) ); 


// return Boolean 


} MFEND 




» listofi(666), listofiC [7, 13,42]), listofiC [7, 13,42.0] ) ; I 


FALSE, TRUE, FALSE 
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6.4 Comparing Objects 

When comparing Mu PAD objects, one has to distinguish between structural 
and numerical comparisons. Structural comparison compares two objects with 
respect to the internal order of Mu PAD objects. For numerical data this result 
may differ from the one derived by a numerical comparison. For example, the 
values 0.5 and ^ are numerically equal but differ in their internal representation 
and thus are unequal with respect to the internal order of Mu PAD objects. 



6.4.1 Structural Comparison 

To speed up structural comparison of arbitrary Mu PAD objects, so-called signa- 
tures (section 4.4.2) are used. They define the internal order of Mu PAD objects. 
Also refer to the built-in function sysorder. 

Note: After constructing or manipulating Mu PAD objects, the signature of the 
corresponding objects must be re-calculated by use of routine MFsig. Otherwise 
two objects may not be noticed as equal even if they are (p. 32, p. 72). 



MFcmp Compares with respect to the internal term order 

■ int MFcmp ( MTcell object 1, MTcell object2 ) 

MFcmp compares two objects with respect to the internal order of Mu PAD objects. It 
returns the value 0 if both objects are equal, value -1 if object 1 is less than object2 
and the value 1 if object 1 is greater than object2. 



MFequal Equal with respect to the internal term order 

■ MTbool MFequal ( MTcell objectl, MTcell object2 ) 

MFequal compares two objects with respect to the internal order of Mu PAD objects 
and returns true if both objects are equal. Otherwise it returns false. 



6.4.2 Numerical Comparison 

The following routines must be used only for numerical values (see MFisNumber)! 
For efficiency, no type checking is done and the kernel may crash otherwise. 



MFeq Equal with respect to the numerical order 

■ MTbool MFeq ( MTcell numl, MTcell num2 ) 

MFeq returns true if numl = num2 and otherwise false. Both arguments must be 
numbers. Refer to MFisNumber for valid data types. 
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MFge 



Greater or equal with respect to the numerical order 



■ MTbool MFge ( MTcell numl, MTcell num2 ) 

MFge returns true if numl > num2 and otherwise false. Both arguments must be 
numbers. Refer to MFisNumber for valid data types. 



MFgt Greater with respect to the numerical order 

■ MTbool MFgt ( MTcell numl, MTcell num2 ) 

MFgt returns true if numl > num2 and otherwise false. Both arguments must be 
numbers. Refer to MFisNumber for valid data types. 



MFle Less or equal with respect to the numerical order 

■ MTbool MFle ( MTcell numl, MTcell num2 ) 

MFle returns true if numl < num2 and otherwise false. Both arguments must be 
numbers. Refer to MFisNumber for valid data types. 



MFlt Less with respect to the numerical order 

■ MTbool MFlt ( MTcell numl, MTcell num2 ) 

MFlt returns true if numl < num2 and otherwise false. Both arguments must be 
numbers. Refer to MFisNumber for valid data types. 



MFneq Unequal with respect to the numerical order 

■ MTbool MFneq ( MTcell numl, MTcell num2 ) 

MFneq returns true if numl / num2 and otherwise false. Both arguments must be 
numbers. Refer to MFisNumber for valid data types. 



Examples 

• sequal(a,b) returns TRUE if a=b with respect to the internal term order. 
The result may differ from that derived using a numerical comparison routine. 



» read ( "Makemod" ) ( "exa060400a" ) : 




MFUNC( sequal, MCnop ) 


// function ^sequal* expects 


{ MFnargsCheck(2) ; 


// two arguments, it gets and 


MTcell a=MFarg(l), b=MFarg(2) ; 


// compares them with respect 


MFreturnC MFbool(MFequal(a,b) ) 
} MFEND 


) ; //to the internal term order 


» sequal("a" , "a") , sequal(l/2,0.5) , 
TRUE, FALSE, TRUE 


sequal (7, 7) ; 
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• The function nequal(a,b) returns UNKNOWN if a or b is not a number. It 
returns TRUE if a=b with respect to the numerical order and otherwise FALSE. 



» readC'Makemod") ("exa060400b'‘) : 




MFUNC( nequal, MCnop ) 


// function ^nequal ^ 


{ MFnargsCheck(2) ; 


// expects two arguments 


MTcell a=MFarg(l): 


// gets first argument 


HTcell b=MFarg(2); 


// gets second argument 


if ( !MFisNumber(a) 1 I !MFisNumber(b) ) 


// numbers expected 


MFreturn(MFcopy(MVunknown) ) ; 




MFreturnC MFbool(MFeq(a,b) ) ); 
} MFEND 


// numerical comparison 


» nequal (7, "a") , nequal(l/2,0.5) , nequal (7, 13) ; I 


UNKNOWN, TRUE, FALSE 


1 



6.5 Data Conversion 

Data conversion is an important aspect of module programming due to the 
fact that C/C++ algorithms which users wish to integrate often use their own 
special purpose data structures to offer high performance solutions. 

MAPI provides conversion routines for basic C/C++ data types, for complex, 
rational and arbitrary precision numbers as well as for Mu PAD expressions and 
C/C++ character strings. Table 6.2 lists the routines described in this section. 
Additional routines for conversions between Mu PAD data structures, e.g. poly- 
nomials and lists (MFpoly21ist), are listed in section 6.7 with the description 
of the corresponding data types. 



Table 6.2: Data Conversion Routines 



Routine 


From/To 


To/From 


MFident 


DOM.IDENT 


char* 


MFstring 


DOM_STRING 


char* 


MFbool, MFboolS 


DOM.BOOL 


MTbool 


MFdouble, MFf loat 


D0M_FL0AT 


double, float 


MFlong, MFint 


DOM.INT 


long, int 


MFcomplex, -Im, -Re 


D0M_C0MPLEX 


D0M_FL0AT, MCinteger, DOM.RAT 


MFrat, -Den, -Num 


D0M_RAT 


DOM.FLOAT, MCinteger 


MFpari 


MCnumber 


GEN 


MF, MFexpr2text 


any type 


char* 
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6.5.1 Basic C/C++ Data Types 

Conversion routines listed here can be used to interface algorithms operating 
on basic C/C++ data types and also for constructing MuPAD data structures. 
Conversion between MuPAD Booleans (D0M_B00L) and C/C++ Booleans is spe- 
cial since MuPAD uses a 3-state logic. Refer to section 4.5.3 for details. 

MuPAD identifiers (DOM.IDENT) are converted into C/C++ character strings 
due to the fact that C/C++ offers no appropriate data type. As for MuPAD 
strings (DOM_STRING), when converting MuPAD identifiers to C/C++ the user 
can choose if he/she wishes a reference to the underlying C/C++ character 
string of the object or a physical copy of it. 



MFbool Converts Boolean with respect to a 2-state logic 

■ MTcell MFbool ( MTbool boolean ) 

MFbool converts a C/C++ Boolean into a MuPAD Boolean (D0M_B00L). This routine 
uses a 2-state logic as usual in C/C++. The C/C++ value 0 is converted into FALSE. 
All other values are converted into TRUE. 

■ MTbool MFbool ( MTcell boolean ) 

MFbool converts a MuPAD Boolean (D0M_B00L) into a C/C++ Boolean. This routine 
uses a 2-state logic as usual in C/C++. The value UNKNOWN is converted into false. 



MFboolS Converts Boolean with respect to a 3-state logic 

■ MTcell MFboolS ( MTbool boolean ) 

MFboolS converts the C/C++ integer value MCfalse, MCtrue or MCunknown into a 
corresponding MuPAD Boolean of type D0M_B00L. It uses the 3-state logic of MuPAD. 

■ MTbool MFboolS ( MTcell boolean ) 

MFboolS converts a MuPAD Boolean (D0M_B00L) into the corresponding integer value 
MCfalse, MCtrue or MCunknown. It uses the 3-state logic of MuPAD. 



MFdouble Converts floating point numbers 

■ MTcell MFdouble ( double number ) 

MFdouble converts a C/C++ floating-point number (double) into a MuPAD floating- 
point number (D0M_FL0AT). Refer to MF for creating larger floating-point numbers. 

■ double MFdouble ( MTcell number ) 

MFdouble converts any MuPAD number (except complex numbers) into a C/C++ 
floating-point number (double). No type checking is done. Refer to MFisNumber for 
valid data types. Conversion is limited by the hardware representation of machine 
floating-point numbers of type double. 




Data Conversion 



67 



MFfloat Converts floating point numbers 

■ MTcell MFfloat ( float number ) 

Refer to MFdouble. 

■ float MFfloat ( MTcell number ) 

Refer to MFdouble. 



MFident Converts identifier to C/C++ string and vice versa 

■ MTcell MFident ( char* ident ) 

MFident converts a C/C++ character string into a MuPAD identifier (D0M_ IDENT). 

■ char* MFident ( MTcell ident, long option=MCnddr ) 

MFident converts a MuPAD identifier (D0M_ IDENT) into a C/C++ character string. 
By default the address of the underlying C/C++ string of this identifier is returned. 
Setting option to MCcopy, returns a physical copy of this string. This copy must be 
freed by use of MFcfree when it is no longer needed. To avoid side-effects, the 
underlying C/C++ string of ident should not be changed directly. 



MFint Converts integer numbers less than 2^^ 

■ MTcell MFint ( int inum ) 

Refer to MFlong. The limit may be 2^^ on 64bit systems, refer to MFisApm. 

■ int MFint ( MTcell inum ) 

Refer to MFlong. The limit may be 2^^ on 64bit systems, refer to MFisApm. 



MFlong Converts integer numbers less than 2^^ 

■ MTcell MFlong ( long number ) 

MFlong converts a C/C++ integer number into a MuPAD integer (D0M_INT). The 
limit may be 2^^ on 64bit systems, refer to MFisApm. Also refer to MF to create larger 
integer numbers of type D0M_APM. 

■ long MFlong ( MTcell number ) 

MFlong converts a MuPAD integer (D0M_INT) into a C/C++ integer number. The 
limit may be 2^^ on 64bit systems, refer to MFisApm. No type checking is done. 



MFstring Converts character strings 

■ MTcell MFstring ( char* string ) 

MFstring converts a C/C++ character string into a MuPAD string (DOM_STRING). 
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■ char* MFstring ( MTcell stringy long option =MCaddr ) 

MFstring converts a MuPAD string (DOM_STRING) into a C/C++ character string. 
By default the address of the underlying C/C++ string is returned. Setting option 
to MCcopy, returns a physical copy of this string. This copy must be freed by use 
of MFcfree when it is no longer needed. To avoid side-effects, the underlying 
C/C++ string of string should not be changed directly. 



Examples 

• The function f astsin(f ) computes the sin of f using C/C++ machine num- 
ber arithmetic if f is a floating-point number. Otherwise it just returns the 
function call with evaluated arguments. This function is several times faster 
than the one of the MuPAD arbitrary precision arithmetic. 



» read("Makemod")("exa060601a") : 






MFUNC( fastsin, HCnop ) 


// 


function ’fastsin* 


{ MFnargsCheck(l) ; 


// 


expects one argument 


if( !MFisFloat(MFarg(D) ) 


// 


must be a float 


MFreturnC MFcopy(MVargs) ); 


// 


return function call 


double d=MFdouble( HFarg(l) ); 


// 


convert to double 


d = sin( d ) ; 


// 


call C/C++ sin routine 


MFreturnC MFdouble(d) ); 
} MFEND 


// 


return as a DOM^FLOAT 


» fastsin(PI), f astsin(f loat (PI) ) ; 






fastsin(PI) , -0.000000000000002542070579 





• The functions bool2 and bool3 demonstrate the difference between 2-state 
and 3-state Boolean conversion routines. 



» read ( "Makemod" ) ( "exa06050 lb" ) : 






MFUNC( bool2, MCnop ) 


// 


function *bool2’ 


{ MFnargsCheck(l) ; 


// 


expects one argument 


MFargCheck(l,D0M_B00L) ; 


// 


must be a Boolean 


MTbool b=MFbool( MFarg(l) ); 


// 


convert: 2-state logic 


MFreturnC MFbool(b) ) ; 


// 


return reconverted value 


} MFEND 






MFUNC( bool3, MCnop ) 


// 


function *bool3’ 


{ MFnargsCheck(l) ; 


// 


expects one argument 


MFargCheckCl ,D0M_B00L) ; 


// 


must be a Boolean 


MTbool b=MFbool3( MFarg(l) ); 


// 


convert: 3-state logic 


MFreturnC MFbool3(b) ); 


// 


return reconverted value 


} MFEND 






» bool3(UNKN0WN), bool2 (UNKNOWN) ; 






UNKNOWN, FALSE 
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6.5.2 Arbitrary Precision Numbers 

Refer to section 4.5.4 for an introduction to arbitrary precision arithmetic in 
Mu PAD. The following routines allow to convert PARI numbers from/into 
Mu PAD numbers. PARI numbers are C/C++ data structures of type GEN. 
Refer to the User’s Guide to PARI-GP [4] for detailed information. 



MFpari Converts PARI to MuPAD numbers and vice versa 

■ GEN MFpari ( MTcell number ) 

Returns the PARI number which is embedded in the MuPAD cell number. 

■ MTcell MFpari ( GEN number ) 

Returns the MuPAD number created by embedding number into a MuPAD cell. 



Examples 

t The function nothing converts a given MuPAD number into a PARI number 
and re-converts this to a MuPAD number. 



» read("Makemod") ("exa060502a") : 




MFUNC( nothing, MCnop ) 


// function ’nothing’ 


{ MFnargsCheck(l) ; 


// expects one argument 


MFargCheck(l ,MCnumber) ; 


// which is a number 


GEN pnum=MFpari( MFarg(l) ); 


// extract the PARI number 


MFreturnC MFpari(pnum) ); 


// returns a MuPAD number 


} MFEND 




» nothing(l/7) , nothing(42) ; 




1 / 7 , 42 





6.5.3 Strings and Expressions 

MAPI provides routines to convert C/C++ character strings into MuPAD ob- 
jects and vice versa. This is useful for constructing complex as well as large 
objects, e.g. arrays or arbitrary precision integer numbers which cannot repres- 
ented as a C/C++ long. However, since it is time consuming it should be used 
carefully and be avoided in cases where efficiency matters. 



MF Constructs a MuPAD object from a C/C++ string 

■ MTcell MF ( char* string ) 

Refer to MFtext2expr. 
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MFexpr2text Converts a MuPAD object into a C/C-h+ string 

■ char* MFexpr2text ( MTcell expr ) 

MFexpr2text converts the MuPAD object expr into a C/C++ character string. This 
string must be freed by use of MFcf ree when it is no longer needed. 



MFtext2expr Converts a C/C++ string into a MuPAD object 

■ MTcell MFtext2expr ( char* string ) 

MFtext2expr converts a C/C++ string into a MuPAD object of type MTcell. If 
string has a wrong syntax, the current evaluation is aborted with an error message. 



Examples 

• The function ob j ect creates a list containing an equation of an identifier and 
an arbitrary precision number. Also refer to example exa060300b on page 62. 



» readC'Makemod") ("exa060503a") : 

MFUNCC object, MCnop ) 

{ MTcell list=MF("[large=123456789012345678901234567890123]”) ; 

MFreturnC list ) ; // this is a list 

} MFEND 

» objectO; 

[large = 123456789012345678901234567890123] 



6.6 Basic Object Manipulation 

Refer to section 4.4 for an introduction to the MuPAD memory management. 
Also refer to MFglobal. The following routines provide an interface to the basic 
manipulation routines for MuPAD cells and trees. 



MFchange Physically copies a cell 

■ MTcell MFchange ( MTcell* object ) 

MFchange physically copies (page 33) the cell object and returns the new cell. It must 
be used to avoid side-effects when changing an object. Since MFchange may destroy 
the unique data representation (section 4.4.3), it should be used carefully and only if 
necessary. Physical copies must be freed if they are no longer needed. Before a cell 
is physically copied it must be logically copied by use of MFcopy. MFchange 
must not be applied to any of the objects listed in section 6.7.1. 
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MFcopy Logically copies a cell 

■ MTcell MFcopy ( MTcell object ) 

MFcopy logically copies (page 33) the cell object and returns the new cell. Logically 
copies must be freed if they are no longer needed. Note that a logically copy 
must not be freed if it is used as an argument for the routine MFchange. 



MFfree Frees a cell 

■ void MFfree ( MTcell object ) 

MFfree frees the cell object by decrementing its reference counter (refer to section 
4.4.3). If the reference counter is zero, the cell object is physically freed. This 
routine frees its argument. MFfree must not be applied to any of the objects 
listed in section 6.7.1 as well as to cells with uninitialized operands. 



MFnops Returns/Changes the number of operands 

■ long MFnops ( MTcell object ) 

MFnops returns the number of operands (children) of the cell object. 

■ void MFnops ( MTcell* object, long num ) 

MFnops changes the number of operands (children) of the cell ^object to the value 
num. This de- respectively increases the length of the point block of the cell (refer 
to figure 4.4). Newly appended operands are uninitialized and must be set 
to (copies of) valid MuPAD objects before further processing this cell. The 
signature of the cell (refer to section 4.4.2) must be re-calculated by use of MFsig. 



MFmemGet Returns the memory block of a cell for reading 

■ char* MFmemGet ( MTcell object, long offset=0 ) 

MFmemGet returns the address of the memory block (refer to figure 4.4) of the cell 
object for reading. The address may be incremented by an offset of offset bytes. 



MFmemSet Returns the memory block of a cell for writing 

■ char* MFmemSet ( MTcell object, long offset=0 ) 

MFmemSet returns the address of the memory block (refer to figure 4.4) of the cell 
object for writing. The address may be incremented by an offset of offset bytes. 



MFop Returns/Changes the n-th operand 

■ MTcell MFop ( MTcell object, long n ) 

MFop returns the n-th operand of the cell object. The operand is not copied. 
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■ MTcell MFop ( MTcell object^ long n, MTcell value ) 
Refer to MFopSet. 



MFopSet Sets the n-th operand of a cell 

■ MTcell MFopSet ( MTcell object, long n, MTcell value ) 

MFopSet sets the n-th operand of the cell object to value. The old operand is 
overwritten without being freed. The argument value is not copied by MFopSet. 



MFopFree Frees the n-th operand of a cell 

■ MTcell MFopFree ( MTcell object, long n ) 

MFopFree frees the n-th operand of the cell object. MFopFree must not be applied 
to an uninitialized operand. 



MFopSubs Substitutes the n-th operand of a cell 

■ MTcell MFopSubs ( MTcell* object, long n, MTcell value ) 

MFopSubs substitutes the n-th operand of the cell *object with value. In contrast 
to the routine MFopSet, MFopSubs uses the routines MFcopy and MFchange to 
create a new instance of *object and frees the old operand before setting 
the new value. MFopSubs must not be applied to an uninitialized operand. 
The argument value is not copied by MFopSubs. 



MFsig Recalculates the signature of a cell 

■ void MFsig ( MTcell object ) 

MFsig calculates and sets the signature of the cell object. Refer to section 4.4.2 for 
details. MFsig must not be applied to cells with uninitialized operands. 



MFsize Gets/Changes the length of the memory block 

■ long MFsize ( MTcell object ) 

MFsize returns the length of the memory block of the cell object. 

■ long MFsize ( MTcell* object, long n ) 

MFsize changes the length of the memory block of the cell object to a new length 
that is at least n bytes long. MFsize returns the new length. 

Examples 

• Function listl demonstrates how to set, get and substitute operands of 
a Mu PAD object. Note, that MFopSubs creates a new instance of the list 1 
respectively k in order to avoid any side-effects when substituting the operand. 
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» readC'Makemod") ("exa060600a") : 






MFUNC( listl, MCnop ) 


// 


function ’listl ^ 


{ MTcell l=MFnewList( 2 ); 


// 


a list with two items 


MFopSetC 1, 0, MFidentC’test") ); 


// 


initializes first item 


MFopSet( 1, 1, MFcopy(MVtrue) ); 


// 


initializes second item 


MFsigC 1 ); 


// 


calculates signature 


MTcell k=l; 


// 


use a new variable 


MFopSubsC «:k, 1, MFcopy(MFop(l,0)) ); 


// 


subs. 2nd item ([0,1,..] 


MFoutC 1 ); 


// 


1 was not changed 


MFfreeC 1 ); 


// 


1 is not longer needed 


MFreturnC k ) ; 


// 


return it as the result 


} MFEND 






» listlC): 






[test, TRUE] [test, test] 







• Function list 2 demonstrates how to change the number of operands of a cell 
and how to access and copy them. 



» readC'Makemod") ("exa060600b") : 

MFUNC( list2, MCnop ) 

{ MTcell l=MFnewList( 1 ); 

MFop( 1, 0, MFlongdS) ); 
MFsig( 1 ); 

MFout( 1 ); 

MFnopsC &1, 2 ); 

MFop( 1, 1, MFlong(42) ); 
MFsigC 1 ); 

MFout( 1 ); 

MTcell r=MFcopy( MFop(l,l) ); 
MFfreeC 1 ); 

MFreturnC r ) ; 

} MFEND 

>> list2() ; 

[13] [13, 42]42 



// function ’list2’ 

// a list with two items 
// initializes first item 
// calculates signature 
// displays the list 1 
// adds another item to 1 
// initializes second item 
// recalculates signature 
// displays the list 1 
// gets/copies second item 
// frees 1 and all operands 
// return it as the result 



6.7 Constructing MuPAD Objects 

All MuPAD objects which are not predefined as special objects (refer to section 
6.7.1) are constructed using MAPI constructor routines. For most data types 
D0M_XXX a constructor routine MFnewXxx is available, e.g. lists (DOM.LIST) can 
be created using the MFnewList. 

Refer to section 4.4 for an introduction to the MuPAD memory management. 
Read section 4.5 for information about data types supported by MAPI. Other 
MuPAD objects can be created with the routine MF and manipulated with the 
routines listed in section 6.6 as well as with MuPAD functions called by MFcall. 
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6.7.1 Special MuPAD Objects 

Certain often used MuPAD objects are predefined and made available via MAPI 
variables. Most of them are expected to be stored as unique data (see section 
4.4.3). To use one of these objects, e.g. for constructing new data, just make a 
logical copy of it using MFcopy. 

Table 6.3 lists all classes of predefined MuPAD objects. Refer to the MuPAD 
User’s Manual [50] for additional information. 



Table 6.3: Predefined MuPAD Objects 



Domain 


MuPAD Object 


Description 


D0M_B00L 


TRUE, FALSE, UNKNOWN 


3-state logic 


DOM.INT 


-2, -1, 0, 1, 2 


integer values 


D0M_RAT 


1 

2 


rational value 


D0M_C0MPLEX 


I 


complex value 


D0M_FAIL 


FAIL 


action failed 


DOM.NIL 


NIL 


undefined 


D0M_NULL 


nullO 


space object 



For each of the objects listed in table 6.3 and described on the following pages, 
a fast type checking routine MFisXxx is available. Refer to the routine MFis. . . 
for detailed information. 



MVf ail Special object FAIL 

■ MTcell MVfail 

The special object FAIL (D0M_FAIL). New instances can be created by use of MFcopy. 
MVfail must not be changed by MFchange. 



MVnil Special object NIL 

■ MTcell MVnil 

The special object NIL (D0M_NIL). New instances can be created by use of MFcopy. 
MVnil must not be changed by MFchange. 



MVnull Special object null() 

■ MTcell MVnull 

The special object nullO (D0M_NULL). New instances can be created by use of 
MFcopy. MVnull must not be changed by MFchange. 
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MVf alse Boolean value FALSE 

■ MTcell MVfalse 

The Boolean constant FALSE (D0M_B00L). New instances can be created by use of 
MFcopy. MVfalse must not be changed by MFchange. 



MVtrue Boolean value TRUE 

■ MTcell MVtrue 

The Boolean constant TRUE (D0M_B00L). New instances can be created by use of 
MFcopy. MVtrue must not be changed by MFchange. 



MVunknown Boolean value UNKNOWN 

■ MTcell MVunknown 

The Boolean constant UNKNOWN (D0M_B00L). New instances can be created by use of 
MFcopy. MVunknown must not be changed by MFchange. 



MVhalf Rational number | 

■ MTcell MVhalf 

The numerical constant | (D0M_RAT). New instances can be created by use of MFcopy. 
MVhalf must not be changed by MFchange. 



MVi Complex number I 

■ MTcell MVi 

The numerical constant I (D0M_ COMPLEX). New instances can be created by use of 

MFcopy. MVi must not be changed by MFchange. 



MVone Integer number 1 

■ MTcell MVone 

The numerical constant 1 (D0M_INT). New instances can be created by use of MFcopy. 
MVone must not be changed by MFchange. 



MVone _ Integer number -1 

■ MTcell MVone_ 

The numerical constant -1 (D0M_INT). New instances can be created by use of MFcopy. 
MVone_ must not be changed by MFchange. 
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MVtWO Integer number 2 

■ MTcell MVtWO 

The numerical constant 2 (D0M_INT). New instances can be created by use of MFcopy. 
MVtWO must not be changed by MFchange. 



MVtWO_ Integer number -2 

■ MTcell MVtwo_ 

The numerical constant -2 (D0M_INT). New instances can be created by use of MFcopy. 
MVtWO- must not be changed by MFchange. 



MVzero Integer number 0 

■ MTcell MVzero 

The numerical constant 0 (DOM-INT). New instances can be created by use of MFcopy. 
MVzero must not be changed by MFchange. 



Examples 

• The function isone demonstrates the usage of predefined MuPAD objects. 



» read("Makemod")("exa060701a") : 




MFUNC( isone, MCnop ) 


// function ^ isone ^ 


{ MFnargsCheckC 1 ); 


// expects one argument 


MFargCheckC 1, MCnumber ); 


// which is a number 


if( MFeq(MFarg(l),MVone) ) { 


// no copy is needed 


MFreturnC MFcopy (MVtrue) ); 


// a copy is needed 


} 


// use brackets ! ! ! ! 


MFreturnC MFcopy(MVf alse) ); 
} MFEND 


// a copy is needed 


» isone(42), isone(l); 




FALSE, TRUE 





6.7.2 Strings and Identifiers 

MuPAD strings and identifiers are created from C/C++ character strings by us- 
ing the conversion routines described in section 6.5.1. To identify specific iden- 
tifiers and character strings, the routine MFisIdent respectively MFisString 
can be used. The following additional routines are available: 
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MFlenIdent Returns the length of an identifier 

■ long MFlenIdent ( MTcell ident ) 

MFlenIdent returns the length of the name of identifier (D0M_ IDENT) ident. 



MFlenString Returns the length of a string 

■ long MFlenString ( MTcell string ) 

MFlenString returns the length of the character string (DOM_STRING) string. 



MFnewIdent Creates a new identifier 

■ MTcell MFnewIdent ( char* string ) 

Refer to MFident. 



MFnewString Creates a new string 

■ MTcell MFnewString ( char* string ) 

Refer to MFstring. 



Examples 

• The routine ident2string gets one argument which is a MuPAD identifier 
and converts it into a MuPAD character string. 



» read("Makenio<i")("exa060702a") : 




1 


MFUNC( ident2string, MCnop ) 


// function 


’ ident2string’ I 


{ MFnargsCheck( 1 ); 


// expects one argument 1 


MFargCheckC 1, DOM.IDENT ); 
char* ctext ; 


// which is 


an identifier 


text = MFident ( MFarg(l) ); 
MTcell mtext; 


// converts 


to C/C++ string 


mtext = MFstringC text ) ; 


// converts 


to MuPAD string 


MFreturnC MFstring(text) ); 
} MFEND 


// returns 


to MuPAD 


» ident2string(waldemar) ; 






"waldemar” 







• The function reverse reverses a MuPAD character string by swapping the 
order of its characters. Also refer to routine MFcfree and example exa061002a 
on page 104 for related information. 
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» read("Makemod")("exa060702b") : 






MFUNC( reverse, MCnop ) 


// 


function * reverse* 


{ MFnargsCheckC 1 ); 


// 


expects one argument 


MFargCheckC 1, DOM.STRING ); 


// 


which is a string 


MTcell s=MFarg( 1 ); 


// 


gets the NuPAD string 


char* t=MFstring( s, MCcopy ); 


// 


converts to C string 


int i=0 ; 


// 


first char, of string 


int j=strlen(t)-l; 


// 


last char, of string 


for( ;i<j; ) { 


// 


reverses the copy of 


char c=t [i] ; 


// 


the C string by swapping 


t[i++]=t [j] ; 


// 


the characters 


0 
II 

1 — 1 

1 
1 

) 

1 1 

•p 


// 


successively 


} 


// 


all its characters 


s = MFstringC t ) ; 


// 


converts to MuPAD string 


MFcfreeC t ) ; 


// 


frees allocated C string 


MFreturnC s ) ; 


// 


returns the MuPAD string 


} MFEND 






» reverse ( "waldemar" ) ; 






"ramedlaw" 







6.7.3 Booleans 

Mu PAD Booleans are created either from C/C++ Booleans using the conversion 
routines described in section 6.5.1 (also refer to section 4.5.3) or by logically 
copying the predefined Boolean constants MVf alse, MVtrue and MVunknown. 

To identify Boolean constants, the routines MFisBool, MFisTrue, MFisFalse 
and MFisUnknown are available. In addition to this, the following routines can 
be used to operate on Booleans: 



MFnot Negates a Boolean constant 

■ MTcell MFnot ( MTcell object ) 

MFnot returns the Boolean value noi(object), where object must be one of the 
Boolean constants FALSE, TRUE and UNKNOWN. Using a 3-state logic, noi(UNKNOWN) is 
UNKNOWN. Other Boolean operators -built-in or library functions- can be called using 
MFcall. MFnot frees its argument. 

Examples 

• The function i snot prime (number) checks whether number is a prime number 
or not and returns the negated result. This example demonstrates the usage of 
the routine MFnot and also shows a typical application of the routine MFcall. 
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» read("Hakemod")("exa060703a") : 
MFUNC( isnotprime, MCnop ) 


// function ’isnotprime’ 


{ MFnargsCheckC 1 ) ; 


// expects one argument 


MFargCheckC 1, MCinteger ); 


// which is any integer 


MTcell r=MFcall( "isprime", 


1, MFcopy(MFargd) ) ); //is prime? 


MFreturnC MFnot(r) ); 


// returns negated value 


} MFEND 

» isnotprime (6 ) , isnotprime(7) ; 
TRUE, FALSE 





6.7,4 Complex and Rational Numbers 

Since complex and rational numbers are no plain data types of C/C++, corres- 
ponding MuPAD objects must be constructed instead of being directly conver- 
ted from C/C++ values. Also refer to section 4.5.4. The following routines are 
available to operate on complex and rational numbers: 



MFcomplex Constructs a complex number 

■ MTcell MFcomplex ( MTcell re, MTcell im ) 

MFcomplex constructs a complex number (D0M_C0MPLEX) with the real part re and the 
imaginary part im. Both arguments must be of type D0M_APM, D0M_FL0AT, D0M_INT 
or D0M_RAT. MFcomplex frees its arguments. 



MFcomplexIm Returns the imaginary part of a complex number 

■ MTcell MFcomplexIm ( MTcell num ) 

MFcomplexIm returns the imaginary part of num. num must be of type DOM_ COMPLEX. 



MFcomplexRe Returns the real part of a complex number 

■ MTcell MFcomplexRe ( MTcell num ) 

MFcomplexRe returns the real part of num. num must be of type D0M_ COMPLEX. 



MFrat Constructs a rational number 

■ MTcell MFrat ( MTcell numer, MTcell denom ) 

MFrat constructs a rational number (D0M_RAT) with the numerator numer and the 
denominator denom. Both arguments must be of type D0M_APM or D0M_INT. MFrat 
frees its arguments. 

■ MTcell MFrat ( long numer, long denom ) 

This routine expects C/C++ integers instead of MuPAD integers as arguments. 
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MFratDen Returns the denominator of a rational number 

■ MTcell MFratDen ( MTcell num ) 

MFratDen returns the denominator of num. num must be of type D0M_RAT. 



MFratNum Returns the numerator of a rational number 

■ MTcell MFratNum ( MTcell num ) 

MFratNum returns the numerator of num. num must be of type D0M_RAT. 



Examples 

• cplx demonstrates the construction of rational and complex Mu PAD numbers. 



» read ( "Makemod" ) ( "exa060704a" ) : || 


MFUNC( cplx, MCnop ) 


// function ^cplx* 


{ MFnargsCheckC 1 ); 


// expects one arg. 


MFargCheckC 1, MCnumber ); 


// which is a number 


if ( MFisComplex(MFarg(l) ) ) { 


// it recognizes a 


MFputsC "Complex number" ); 


// complex number 


MFreturnC MFcopy(MVnull) ); 


// and returns it 


} 


// directly, creates 


MTcell r=MFrat (MFcopy (MVtwo ) , MFlong (3 ) ) ; 


// the rational 2/3 


MTcell c=MFcomplex(r , MFcopy (MFarg( 1) )) ; 


// a complex number 


MFreturnC c ) ; 


// return it 


} MFEND 


» cplx(I), cplx(13), cplx(3.14), cplx(O), domtype(cplx(0) ) ; 


Complex number 


2/3 + 13*1, 0.6666666666 + 3.14*1, 2/3, DOM. 


z 



6.7.5 Lists 

Lists (D0M_L1ST, figure 4.6) are an important data structure in MuPAD. They 
are often used and can be converted from/into various other data structures, 
e.g. finite sets, tables, arrays and polynomials. 

The following routines are available to construct and to operate on lists. Also 
all basic manipulation routines listed in section 6.6 can be applied to them. 



MFfreeList Frees the n-th list entry 

■ MTcell MFfreeList ( MTcell* list, long n ) 

MFfreeList frees the n-th entry of *list. MFfreeList must not be applied to 
an uninitialized list entry. 
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MFgetList Returns the n-th list entry 

■ MTcell MFgetList ( MTcell* list, long n ) 

MFgetList returns the n-th entry of *list. The list entry is not copied. 



MFnewList Creates an empty list 

■ MTcell MFnewList ( long n ) 

MFnewList creates an empty list of length n. The list entries are uninitialized 
and must be set to (copies of) valid objects before further processing this 
list. After all entries are inserted, the signature must be calculated by use of MFsig. 



MFnopsList Returns/Changes the number of list entries 

■ long MFnopsList ( MTcell list ) 

MFnopsList returns the number of entries of list. 

■ void MFnopsList ( MTcell* list, long n ) 

MFnopsList changes the number of entries of *list. This de- respectively increases 
the length of the point block of the cell (refer to figure 4.4). Newly appended 
list entries are uninitialized and must be set to (copies of) valid MuPAD 
objects before further processing this list. When shorting a list, elements are 
freed automatically. The signature of the list must be re-calculated by use of MFsig. 



MFsetList Sets the n-th list entry 

■ MTcell MFsetList ( MTcell* list, long n, MTcell value ) 

MFsetList sets the n-th entry of *list to value. The old entry is overwritten without 
being freed. The argument value is not copied by MFsetList. 



MFsubsList Substitutes the n-th operand 

■ MTcell MFsubsList ( MTcell* list, long n, MTcell value ) 

MFsubsList sets the n-th entry of *list to value. In contrast to MFsetList, 
MFsubsList uses the routines MFcopy and MFchange to create a new instance 
of *list and frees the old operand before setting the new value. MFsubsList 
must not be applied to an uninitialized list entry. The argument value is 
not copied by MFsubsList. 

Examples 

• Function applist appends an element to a list. Note, that removing the 
MFsig line would result in an incorrect list: the comparison would fail! 
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» read("Makemod”) ("exa060705a") : 

MFUNC( applist, MCnop ) 

{ MFnargsCheckC 2 ); 

MFargCheckC 1, D0M_LIST ); 
MTcell lis=MFcopy( MFarg(l) ); 
MTcell ent=MFcopy( MFarg(2) ); 
long len=MFnopsList(lis) ; 
MFchangeC &lis ); 

MFnopsListC &lis, len+1 ); 
MFsetList ( &lis, len, ent ); 
MFsigC lis ); 

MFreturnC lis ); 

} MFEND 



// function ^ applist^ 

// expects two arguments 
// first must be a list 
// we will need a copy 
// we will need a copy 
// determines list length 
// avoids any side effects 
// appends a new element 
// sets the new element 
// recalculates signature 
// returns the new list 



applistC Cl, 2, 3, 4], 5 ): bool( */. = [1,2, 3, 4, 5] ); 



• The function revlist reverses a list by swapping the order of its elements. 



» readC'Makemod") ("exa060705b") : 

MFUNC( revlist, MCnop ) 

{ MFnargsCheckC 1 ); 

MFargCheckC 1, D0M_LIST ); 

MTcell l=MFcopyC MFargCl) ); 
long n=MFnopsList Cl)-1 ; 

MFchangeC &1 ); 

forC long i=0; i<n; i++, n — ) { 
MTcell e=MFgetListC &1, i ); 
MFsetList C &1, i, MFgetList C&l,n) ); 
MFsetList C &1, n, e ); 

} 

MFsigC 1 ); 

MFreturnC 1 ); 

} MFEND 



// function ^revlist ^ 

// expects two arguments 
// first must be a list 
// we will need a copy 
// determines last index 
// avoids any side effects 
// swap all list entries 
// by just moving them 



// recalculates signature 
// returns the new list 



» 1: = [1,2,3,4,5] : revlistCl): boolCl=revlist C*/.) ) ; 



6.7,6 Expressions 

Expression (D0M_EXPR, figure 4.6) is one of the most important data structures 
in Mu PAD. It represents function calls and the special type expression sequence 
(_exprseq). Specific expressions can be identified with routine MFisExpr. 

Besides the routines described below, all routines listed in section 6.6 can be 
applied to expressions. Refer also to the routines MF, MFexpr2text and MFeval. 
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MFfreeExpr Frees the n-th operand of an expression 

■ MTcell MFfreeExpr ( MTcell* expr, long n ) 

MFfreeExpr frees the n-th operand of *expr. MFfreeExpr must not be applied to 
an uninitialized operand. 



MFgetExpr Returns the n-th operand of an expression 

■ MTcell MFgetExpr ( MTcell* expr, long n ) 

MFgetExpr returns the n-th operand of *expr. The operand is not copied. 



MFnewExpr Creates an expression 

■ MTcell MFnewExpr ( MTcell func, long n=0 ) 

MFnewExpr creates an expression with n-|-l operands. The 0th operand is set to func 
which is expected to be an executable MuPAD object, e.g. a procedure (D0M_PR0C) 
or an identifier like sin. The other operands are uninitialized and must be 
set to (copies of) valid objects before further processing this expression. 
After all operands are set, the signature of the expression must be calculated by use 
of MFsig. The argument func is not copied by MFnewExpr. 

■ MTcell MFnewExpr ( long n, . . . ) 

MFnewExpr creates an expression with n operands. The new expression is initial- 
ized with the n arguments given for ”...” and the signature is calculated and set 
automatically. MFnewExpr does not copy its arguments. 



MFnewExprSeq Creates an expression sequence 

■ MTcell MFnewExprSeq ( long n, . . . ) 

MFnewExprSeq creates an expression sequence with n-f 1 operands. The new expres- 
sion is initialized with the identifier _exprseq as its 0th operand and the n arguments 
given by ”. . .” for the rest of the operands. The signature is calculated and set auto- 
matically. MFnewExprSeq does not copy its arguments. 



MFnopsExpr Returns/Changes the number of operands 

■ long MFnopsExpr ( MTcell expr ) 

MFnopsExpr returns the number of operands of expr. 

■ void MFnopsExpr ( MTcell* expr, long n ) 

MFnopsExpr changes the number of operands of *expr. This de- or increases the point 
block length of the cell (refer to figure 4.4). Appended operands are uninitialized 
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and must be set to (copies of) Mu PAD objects before further processing 
this expression. The signature must be re-calculated with MFsig. 



MFsetExpr Sets the n-th operand of an expression 

■ MTcell MFsetExpr ( MTcell* expr, long n, MTcell value ) 

MFsetExpr sets the n-th operand of *expr to value. The old operand is overwritten 
without being freed. The argument value is not copied by MFsetExpr. 



MF subs Expr Substitutes the n-th operand of an expression 

■ MTcell MFsubsExpr ( MTcell* expr, long n, MTcell value ) 

MFsubsExpr sets the n-th operand of *expr to value. In contrast to MFsetExpr, 
MFsubsExpr uses the routines MFcopy and MFchange to create a new instance 
of *expr and frees the old operand before setting the new value. The 
argument value is not copied by MFsubsExpr. 

Examples 

• The function fcomp(f ) constructs the n-th composition of the function f . 



» readC'Makemod") ("exa060706a") : 

MTcell rec( MTcell f, long n ) { if (!n) return (MFcopy (MVnull )) ; 
if (n==l) return (MFnewExprd, MFcopy (f ))) ; 
else return (MFnewExpr (2, MFcopy (f ) ,rec(f, — n))); } 

MFUNC( fcomp, MCnop ) // function *fcomp^ 

{ MFnargsCheck(2) ; MFargCheck(2, D0M_INT) ; // second is integer 

MFreturn(rec(MFarg(l) ,MFlong(MFarg(2)))) ; // creates expression 
} MFEND 

» fcomp(f,l)> fcomp(f,7); 

f(), f(f(f(f(f(f(f())))))) 



6.7.7 Domain Elements 

Domain elements (D0M_EXT, figure 4.6) are used to define high-level data struc- 
tures. Also refer to MFnewDomain and MVdomain. Specific domain elements can 
be identified with routine MFisExt. Besides the routines described below, all 
routines listed in section 6.6 can be applied to domain elements. 



MFdomExt Returns the domain of a domain element 

■ MTcell MFdomExt ( MTcell ext ) 

MFdomExt returns the domain of ext. The domain is not copied. 
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MFfreeExt Frees the n-th operand of a domain element 

■ MTcell MFfreeExt ( MTcell* ext, long n ) 

MFfreeExt frees the n-th operand of *ext. MFfreeExt must not be applied to an 
uninitialized operand. 



MFgetExt Returns the n-th operand of a domain element 

■ MTcell MFgetExt ( MTcell* ext, long n ) 

MFgetExt returns the n-th operand of *ext. The operand is not copied. 



MFnewExt Creates a domain element 

■ MTcell MFnewExt ( MTcell domdin, long n ) 

MFnewExt creates a domain element with n+l operands, where the 0th operand is 
initialized with domain. The signature is calculated and set automatically. MFnewExt 
does not copy its arguments. Also refer to MFnewDomain and MVdomain. 



MFnopsExt Returns/Changes the number of operands 

■ long MFnopsExt ( MTcell ext ) 

MFnopsExt returns the number of operands of ext. 

■ void MFnopsExt ( MTcell* ext, long n ) 

MFnopsExt changes the number of operands of *ext. This de- respectively increases 
the length of the point block of *ext (figure 4.4). Newly appended operands are 
uninitialized and must be set to (copies of) valid MuPAD objects before fur- 
ther processing this element. The signature must be re-calculated with MFsig. 



MFsetExt Set the n-th operand of a domain element 

■ MTcell MFsetExt ( MTcell* ext, long n, MTcell value ) 

MFsetExt sets the n-th operand of *ext to value. The old operand is overwritten 
without being freed. The argument value is not copied by MFsetExt. 



MFsubsExt Substitutes the n-th operand of a domain element 

■ MTcell MFsubsExt ( MTcell* ext, long n, MTcell value ) 

MFsubsExt sets the n-th operand of *ext to value. In contrast to MFsetExt, it uses 
the routines MFcopy and MFchange to create a new instance of *ext and frees 
the old operand before setting the new value. The argument value is not 
copied by MFsubsExt. 
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Examples 

• The function create demonstrates how to construct domain elements. The 
object MVdomain is described on page 90. 



» read ( "Makemod" ) ( "exa060707a" ) : 

MFUNC( create, MCnop ) 

{ MTcell e=MFnewExt( MVdomain, 2 
MFsetExtC &e, 1, MFident ("one") 
MFsetExtC fee, 2, MFidentC'two") 
MFsigC e ); 

MFreturnC e ); 

} MFEND 

» createO; 

new(exa060707a, one, two) 



// function * create^ creates 
) ; //a domain element of the 

) ; // current module domain 

) ; // with two operands 

// calculates the signature 
// returns the domain element 



6.7.8 Sets 

Refer to section 4.5.6 for a brief introduction to finite sets (D0M_SET) in MuPAD. 
Finite sets can be constructed and manipulated using the following routines. 
Using them, no signatures need to be (re-)calculated for finite sets. 



MFdelSet Removes an element from a finite set 

■ MTcell MFdelSet ( MTcell set, MTcell value ) 

MFdelSet returns a new set that contains the elements of set except value. The 
arguments set and value are freed by MFdelSet. 



MFinSet Looks for an element in a finite set 

■ MTbool MFinSet ( MTcell set, MTcell value ) 

MFinSet returns true if value is an element of set. Otherwise it returns false. 



MFinsSet Inserts an element into a finite set 

■ void MFinsSet ( MTcell set, MTcell value ) 

MFinsSet inserts the element value into set. The argument value is not copied 
by MFinsSet. 



MFintersectSet Returns the intersection of two finite sets 

■ MTcell MFintersectSet ( MTcell setl, MTcell set2 ) 

MFintersectSet returns the set of elements which are in set setl and also in set2. 
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MFlist2set Converts a finite list into a finite set 

■ MTcell MFlist2set ( MTcell list ) 

MFlist2set converts the finite list list into a finite set. 

MFminusSet Returns the difference of two finite sets 

■ MTcell MFminusSet ( MTcell setl, MTcell set2 ) 

MFminusSet returns the set of elements which are in setl but not in set2. 



MFnewSet Creates an empty finite set 

■ MTcell MFnewSet ( ) 

MFnewSet creates an empty finite set. 



MFse't21ist Converts a finite set into a finite list 

■ MTcell MFset21ist ( MTcell set ) 

MFset21ist converts the finite set set into a finite list. 



MFunionSet Returns the union of two finite sets 

■ MTcell MFunionSet ( MTcell setl, MTcell set2 ) 

MFunionSet returns the set of elements which are in setl or in set2. 



Examples 

• Function we constructs a finite set using the routines described above. 



|» readC'Makemod'') ("exa060708a") : 

MFUNC( we, MCnop ) 

{ MTcell s=MFnewSet ( ) ; 

MFinsSetC s, MFidentC'you") ); 
MTcell 1=MF( "[me, he]" ); 
MTcell t=MFlist2set( 1 ); 
MFfree( 1 ) ; 

1 = MFunionSet ( s, t ); 

MFfreeC s ); MFfree( t ); 
s = MFident( "he" ); 
t = MFdelSetC 1, s ); 
MFreturnC t ); 

} MFEND 

|» we(), bool( we()={you,me} ); 

{me, you}, TRUE 



// function ’we’ 

// creates a finite set 
// with identifier ’you’ 
// constructs a list 
// converts 1 to a set 
// is no longer needed 
// unites the finite sets 
// is no longer needed 
// with identifier ’he’ 

// removes s from t 
// returns the result 
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6.7.9 Tables 

Refer to section 4.5.6 for a brief introduction to tables (D0M_TABLE) in MuPAD. 
Tables can be constructed and manipulated using the following routines. Using 
them, no signatures need to be calculated for tables. 



MFdelTable Removes the table entry of a given index 

■ MTcell MFdelTable ( MTcell* table, MTcell index ) 

MFdelTable removes the entry index from *table. The argument index is freed 
by MFdelTable. 



MFgetTable Returns the table entry of a given index 

■ MTcell MFgetTable ( MTcell* table, MTcell index ) 

MFgetTable returns the table entry *table[index]. If stable does not contain a 
value for index, the routine returns the object MCnull. 



MFinTable Looks for a table entry under a given index 

■ MTbool MFinTable ( MTcell* table, MTcell index ) 

MFinTable returns true, if *table contains index. Otherwise it returns false. 



MFinsTable Inserts a table entry under a given index 

■ void MFinsTable ( MTcell* table, MTcell index, MTcell value ) 

MFinsTable sets the table entry *table[index] to value. The arguments index 
and value are not copied by MFinsTable. 



MFlist2table Converts a list of equations into a table 

■ MTcell MFlist2table ( MTcell list ) 

MFlist2table converts the list of equations list into a table. 



MFnewTable Creates an empty table 

■ MTcell MFnewTable ( ) 

MFnewTable creates an empty table. 



Converts a table into a list 



MFtable21ist 

■ MTcell MFtable21ist ( MTcell table ) 
MFtable21ist converts table into a finite list. 
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Examples 

• The function tabtest constructs a table using the routines described above. 



» read("Makemod")("exa060709a") : 




MFUNC( tabtest, MCnop ) 


// function ’tabtest’ 


{ MTcell r,s,t = MFnewTableO ; 


// constructs a table 


MFinsTableC &t, MFident ("rose") , MFstring("nice flower") ); I 


MFinsTableC ftt, MFident ( "red" ) , 


MFstring("nice color") ); 


MFdelTableC &t, MFident ("rose") 


) ; // removes an entry 


r = MFident ( "red" ) ; 


// checks if the table 


s = MFbooK MFinTable(&t,r) ); 


// s contains index r? 


MFfree(r); MFfree(s); 


// no longer needed 


s = MFtable21ist(t) ; MFfree(t); 


// convert into a list 


MFreturnC s ) ; 


// returns the Boolean 


} MFEND 




» tabtest 0; 




[red = "nice color"] 





6.7.10 Domains 

Read section 4.5.6 for a brief introduction to domains (DOM.DOMAIN) in MuPAD. 
More detailed information about constructing and using domains are given in 
the MuPAD User’s Manual [50] and in the domains paper [7]. 

Domains can be constructed and manipulated using the following routines. Us- 
ing these routines, no signatures need to be calculated for domains. Also refer 
to the MAPI variable MVdomain. 



MFdel Domain Removes the domain entry of a given index 

■ MTcell MFdelDomain ( MTcell domain^ MTcell index ) 

MFdelDomain removes entry index from domain, index is freed by MFdelDomain. 



MFgetDomain Returns the domain entry of a given index 

■ MTcell MFgetDomain ( MTcell domain, MTcell index ) 

MFgetDomain returns the domain entry domain:: index. If domain does not contain a 
value for index, the routine returns the object FAIL. 



MFinsDomain Inserts a domain entry under a given index 

■ MTcell MFinsDomain ( MTcell domain, MTcell index, MTcell value ) 
MFinsDomain sets the domain entry domain::index to value. The arguments index 
and value are not copied by MFinsDomain. 
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MFnewDoitiain Creates respectively returns a domain 

■ MTcell MFnewDomain ( MTcell domkey, MTbool* is-new ) 

The routine creates a domain (D0M_ DOMAIN) with the key domkey and sets the Boolean 
*is_new to true. If the domain already exists, a copy is returned and *is_new is set 
to false, domkey must be of type D0M_ STRING. Also see MVdomkey and MVdomain. 

■ MTcell MFnewDomain ( MTcell domkey ) 

Same functionality as the one described above, but it does not use the Boolean para- 
meter *is_new to indicate if the returned domain is new or existed before. 



MVdomain The current module domain 

■ MTcell MVdomain 

MVdomain refers to the module domain of the current module function. It can be used 
to create domain elements of the module using the routine MFnewExt or to access 
module domain entries using the routines described above. Also refer to MVdomkey. 
The variable MVdomain can only be used directly within the body of a 
module function and cannot be used within any other C/C++ subroutine. 



MVdomkey Name/Key of the current module domain 

■ MTcell MVdomkey 

MVdomkey contains the domain key (D0M_ STRING) of the current module function. 
Also refer to MVdomain. It can only be used directly within the body of a 
module function and cannot be used within any other C/C++ subroutine. 

Examples 

• The function ismyelem checks if its argument is a domain element and belongs 
to the same domain as ismyelem. Instead of MVdomain the routine MFnewDomain 
and the variable MVdomkey are used to create/copy the module domain. 



» read ( "Makemod" ) ("exa0607 10a") : 




MFUNC( ismyelem, MCnop ) 


// function ^ ismyelem^ 


{ MFnargsCheckC 1 ); 


// expects one argument 


MTcell d=MFnewDomain( MVdomkey ); 


// return the module domain 


MTcell b=MFbool(MFisExt(MFarg(l) ,d)) ; 


// is domain element of d ? 


MFfreeC d ); 
MFreturn( b ) ; 


// d is no longer needed 


} MFEND 




» ismyelem(l), ismyelem(new(exa060710a, "test") ) ; I 


FALSE, TRUE 
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• The next example demonstrates how to insert, read and delete domain entries. 
In contrast to the previous example, the module domain is referenced -without 
copying it- using the variable MVdomain. 



» read("Makemod")("exa060710b") : 

MFUNC( get it, MCnop ) 

{ MTcell i=MFstring( "it” ); 
MTcell e=MFgetDomain( MVdomain, 
MFfreeC i ); MFreturn( e ); 

} MFEND 

MFUNC( set it, MCnop ) 

{ MFnargsCheckC 1 ); 

MTcell i=MFstring( "it" ); 
MTcell v=MFcopy( MFarg(l) ); 
MFinsDomainC MVdomain, i, v ); 
MFreturnC MFcopy(MVnull) ); 

} MFEND 

MFUNC( del it, MCnop ) 

{ MTcell i=MFstring( "it" ); 
MFdelDomainC MVdomain, i ); 
MFreturnC MFcopy(MVnull) ); 

} MFEND 



// function ’get it* 

// constructs domain index 
i ) ; // gets domain entry 

// returns domain entry 

// function ’setit’ 

// accepts one argument 
// constructs domain index 
// copies first argument 
// sets new domain entry 
// returns nothing 

// function ’getit’ 

// constructs domain index 
// deletes domain entry 
// returns nothing 



» getitO, setitC'andi") , getitO, delitO, getitO; 
FAIL, "andi", FAIL 



6.7.11 Arrays 

Read section 4.5.7 for a brief introduction to arrays (D0M_ARRAY). The easiest 
way to define a new array is either converting it from a character string using 
the conversion routine MF or creating it from a list using MFlist2array. 



MFarra.y21ist Converts an array into a list 

■ MTcell MFarray21ist ( MTcell array ) 

MFarray21ist converts the object array (D0M_ ARRAY) into a flat list (D0M_LIST). 



MFdimArray Returns the dimension of an array 

■ long MFdimArray ( MTcell array ) 

MFdimArray returns the dimension of array. Also refer to routine MFrangeArray. 



MFlist2array Converts a list into an array 

■ MTcell MFlist2array ( MTcell iist, long di, long d2=0^ long d3=0 ) 




92 



Application Programming Interface (MAPI) 



MFlist2array converts a list (D0M_LIST) into an array, list must be nested accord- 
ing to the dimension defined by dl, d2, and d3. MFlist2array cannot handle arrays 
of higher dimensions. The range of each dimension dn is set to l..dn. 



MFrange Array Returns the range of a specific dimension of an array 

■ void MFrangeArray ( MTcell array, long dim, long* ], long* r ) 
MFrangeArray returns the range of the dimension dim of array. The variable *1 is 
set to the lower bound and *r to the upper bound of the range of dimension dim. 



Examples 

• The function doarray constructs a two dimensional array from a list, tolist 
converts an array into a flat list. This representation is similar to that used by 
numeric packages like IMSL (section 10.3.1) and NAGC (section 10.3.2). 



» read ( "Makemod" ) ( "exa0607 11a"): 




MFUNC( doarray, MCnop ) 


// function Moarray^ 


{ MTcell L=MF( " [[1,2,3] , [4,5,6]] " ) 


// constructs a list 


MTcell A=MFlist2array( L, 2, 3 ); 


// converts to array 


MFfree( L ); MFreturn( A ); 
} MFEND 


// free list, return a 


MFUNCC dolist, MCnop ) 


// function ’dolist^ 


{ MFnargsCheck( 1 ); 


// expects one argument 


MFargCheckC 1, DOM.ARRAY ); 


// must be an array 


MFreturn( MFarray21ist(MFarg(l) ) ); 
} MFEND 


// returns a flat list 


» A : =doarray ( ) : print(A): dolist(A); 




arrayCl. .2,1. .3,(1, 1)=1,(1,2)=2, (1,3): 
[1,2, 3, 4, 5, 6] 


=3,(2,1)=4,(2,2)=5,(2,3)=6) 



Refer to example exa060900b on page 102 for additional information. 



6.7.12 Polynomials 

Read section 4.5.7 for a brief introduction to polynomials (D0M_P0LY). The 
easiest way to define a polynomial is either converting it from a character string 
using the conversion routine MF or creating it from a list using MFlist2poly. 



MFlist2poly Converts a list into a polynomial 

■ MTcell MFlist2poly ( MTcell list, MTcell v=NULL, MTcell r=NULL ) 
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MFlist2poly converts the list representation list of a polynomial into a polynomial. 
V must contain the list of variables and r may contain the coefficient ring of the 
polynomial. Also refer to the built-in function poly [50]. 

MFpoly21ist Converts a polynomial into its list representation 

■ MTcell MFpoly21ist ( MTcell poly, MTcell* v=NULL, MTcell* r=NULL ) 

MFpoly21ist converts poly into its list representation. If v is unequal to zero, *v 
is assigned the list of variables of poly. If r is unequal to zero, *r is assigned the 
coefficient ring of the polynomial. The operands returned in *v and *r are not 
copied by MFpoly21ist. Also refer to the library function poly21ist [50]. 

MFdegPoly Returns the total degree of a polynomial 

■ long MFdegPoly ( MTcell poly ) 

MFdegPoly returns the total degree of the polynomial poly. It behaves exactly like 
the MuPAD built-in function degree [50]. 

Examples 

• tolist returns a sequence of the list representation, the variables and the 
coefScient ring of a given polynomial, topoly reconverts this into a polynomial. 

» read("Makemod")("exa060712a") : 

MFUNC( tolist, MCnop ) 

{ MFnargsCheckC 1 ); 

MFargCheckC 1, D0M_P0LY ); 

MTcell v,p=MFarg( 1 ); 

MTcell r,l=MFpoly21ist( p, &v, &r ) 

MFcopyC V ); MFcopyC r ); 

MFreturnC MFnewExprSeqO , 1 , v ,r) ); 

} MFEND 

MFUNC( topoly, MCnop ) // function ’topoly’ 

{ MFnargsCheckC 3 ); // expects 3 arguments 

MFargCheckC 1, DOM.LIST ); // first is a list? 

MFargCheckC 2, DOM.LIST ); // second is a list? 

MTcell p=MFargCl) ,v=MFargC2) ,r=MFargC3) ;// gets arguments 

MFreturnC MFlist2polyCp,v,r) ); // returns polynomial 

} MFEND 

» A:=tolistC polyCv"4*w"2+C“42)*w"7, [v,w] ) ): printCA): topolyCA); 

[[1, [4, 2]], [-42, [0, 7]]], [v, w], Expr 
polyC v"4*w"2+C“42)*w"7, [v,w] ) 



// function ’tolist’ 

// expects one argument 
// must be a polynomial 
// gets polynomial 
// converts into a list 
// copies vars and ring 
// returns a sequence 
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6.7.13 Other Objects 

Besides the basic domains listed in table 4.1, Mu PAD provides further data 
types (refer to section 4.5.8) which are currently not directly supported by the 
MuPAD Application Programming Interface. 

Mu PAD objects of other data types can be converted from C/C++ character 
strings by use of routine MF. They can also be constructed and manipulated by 
calling MuPAD built-in and library functions using the routine MFcall. 

As a special feature, so-called MuPAD procedures and expressions can be in- 
cluded into module domains. Refer to section 7.2 for details. 



Examples 

• The function makinc(n) constructs a procedure which increments a given 
number by n. Since MAPI does not support the creation of procedures directly 
with a corresponding constructor, the procedure is converted from a C/C++ 
character string by use of routine MF. Then it is manipulated by calling the 
MuPAD function subs [50]. 



» read ( "Makemod" ) ( "exa0607 13a" ) : 




MFUNC( makinc, MCnop ) 


// function *makinc^ 


{ MFnargsCheckC 1 ); 


// accepts one argument 


MFargCheckC 1, DOM.INT ); 


// which is an integer 


MTcell p,e,r,a=MFcopy( MFarg(l) ); 


// a copy will be needed 


p = MF("proc(x) begin x+y end_proc"' 


; // construct a procedure 


e = MF( ".equal" ); 


// construct indent if ier 


e = BFnewExprC 3, e, MF("y"), a ); 


// construct y=^a* 


p = MFcalK "subs", 2, p, e ); 


// subs( p, y=^a* ) 


MFreturnC p ); 




} MFEND 




» inc7:= mcikinc(7) : type(inc7), inc7(4), 


inc7(-4) ; 


DOM.PROC, 11, 3 





6.8 MuPAD Interpreter Interface 

Module programmers can access the MuPAD interpreter -respectively evaluator- 
to call built-in and library functions as well as to evaluate MuPAD expressions. 

Refer to figure 4.2 and section 4.3 for additional information about data evalu- 
ation in MuPAD. Also read section 7.2 for detailed information about including 
MuPAD procedures and expressions into module domains. 
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6.8.1 Calling Built-in and Library Functions 

MuPAD built-in functions, module functions and library functions are part of 
the MuPAD interpreter respectively must be interpreted by it. Therefore they 
cannot be called directly as usual C/C++ kernel routines but only by use of 
the interpreter interface. The following routines are available to call functions. 



MFcall Calls a MuPAD function 

■ MTcell MFcall ( MTcell func^ long nargs, MTcell . . . ) 

MFcall calls the MuPAD function func with the nargs arguments represented by 
and returns the result of this evaluation. If an error occurs during evaluation, MuPAD 
returns into interactive mode, func can be any valid executable MuPAD object, e.g. 
a built-in function, a procedure, a domain method or an identifier representing such 
an object. MFcall does not copy its arguments but frees them. 

■ MTcell MFcall ( char* func, long nargs, MTcell . . . ) 

This routine has the same functionality as described above. But here, the MuPAD 
function func is specified by a C/C++ character string. 



Examples 

• The function map21ist (list , func) returns a list where each entry list [i] 
is substituted by the result of the function call func (list [i] ). 



» read("Makemod")("exa060801a") : 

MFUNC( map21ist, MCnop ) 

{ MFnargsCheck( 2 ) ; 

MFargCheckC 1, D0M_LIST ); 

MTcell l=MFcopy( MFarg(l) ); 
MFchangeC &1 ); 
long n=MFnopsList ( 1 ); 
whileC n ) { 

MTcell t=MFgetList( &1, — n ); 
MTcell f=MFcopy( MFarg(2) ); 
MTcell e=MFcall( f, 1, t ); 
MFsetListC &1, n, e ) ; 

} 

MFsigC 1 ); 

MFreturn( 1 ) ; 

} MFEND 



// function ’map21ist’ 

// expects two arguments 
// the first one is a list 
// logical and physical copy is 
// needed to avoid side-effects 
// gets the length of the list 
// applies func. to all entries 
// get the next list entry 
// copy the function name 
// execute the function call 
// l[n] was freed by MFcall 
// l[n] is set to fun(l[n]) 

// calculate the signature of 1 
// returns the new list 



» map21ist( [4,9, 16,25] , sqrt); 
[ 2 , 3 , 4 , 5 ] 
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6.8.2 Evaluating MuPAD Objects 

Besides the possibility to call MuPAD functions directly by use of routine MFcall, 
built-in and library function calls can also be constructed in form of MuPAD 
expressions using the routine MFnewExpr. 

Expressions and statements as well as other MuPAD objects can be evaluated 
with the following routines. 



MFeval Evaluates an object 

■ MTcell MFeval ( MTcell object ) 

MFeval evaluates the expression object and returns the result of this evaluation. 
If an error occurs during evaluation, MuPAD returns into interactive mode. Refer 
to figure 4.2 and section 4.3 for a brief introduction to data evaluation in MuPAD. 
MFeval frees its argument. 



MFexec Executes an object 

■ MTcell MFexec ( MTcell object ) 

MFexec executes the statement ob j ect and returns the result of this evaluation. If an 
error occurs during evaluation, MuPAD returns into interactive mode. In contrast to 
MFeval, here, object can be not only an expression but also any MuPAD statement. 
Refer to figure 4.2 and section 4.3 for a brief introduction to data evaluation in 
MuPAD. MFexec frees its argument. 



MFtrap Executes an object in the context of traperror 

■ MTcell MFtrap ( MTcell object, long* error ) 

MFtrap executes object using the MuPAD function traperror (refer to the MuPAD 
User’s Manual [50]), sets the variable terror to 0 (zero) and returns the result of this 
evaluation. If an error occurs during evaluation, terror is set to an error code unequal 
to zero and MFtrap returns MVnull. MFtrap does not return into interactive 
MuPAD mode when an error occurs. Refer to figure 4.2 and section 4.3 for a 
brief introduction to data evaluation in MuPAD. MFtrap frees its argument. 



MFread Reads and executes a MuPAD program 

■ MTcell MFread ( chart name ) 

MFread reads and executes the MuPAD file name using the library function read [50] 
and returns the result of this evaluation. If an error occurs during evaluation, MuPAD 
returns into interactive mode. 
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Examples 

• The function fpi returns an approximative floating point number for tt. 



» read( "Makemod" ) ( "exa060802a" ) : 




MFUNC( fpi, MCnop ) 


// function ^fpi* 


{ MTcell f=MF( "float"); 


// function Afloat’ 


MTcell p=MF("PI"); 


// identifier 


MTcell e=MFnewExpr(2,f ,p) ; 


// == float (PI) 


MFreturnC MFeval(e) ); 
} MFEND 


// evaluates ’e’ 


» fpiO; 




3.141592653 





• The function traptest evaluates its argument using the routine MFtrap and 
returns the result. If an error occurs, it displays the corresponding error code. 



» read( "Makemod" ) ("exa060802b") : 




MFUNC( traptest, MChold ) 


// function ^traptest’ 


{ MFnargsCheckC 1 ); 


// expects one argument 


long errn; 


// error flag: 0=0K 


MTcell result=MFtrap( MFarg(l), &errn ) 


// "save" evaluation 


if (errn) MFprintf ("ErrNum= */,ld\n" ,errn) 


; // prints error code 


else MFprintf ("Result= "); 


// or result message 


MFreturnC result ); 


// returns result 


} MFEND 




» A:=traptest(sin(3.4) ) : print(A): traptest (ln(0) ) ; I 


Result= -0.255541102 




ErrNum= 1028 






6.8.3 Accessing MuPAD Variables 

The following routines allow module programmers to access MuPAD variables 
defined on the MuPAD language level. For example, this can be used to read-out 
and/or change MuPAD environment variables like PRETTY_PRINT [50], DIGITS 
[50], etc as well as arbitrary user variables. 



MFgetVar Returns the value of a MuPAD variable 

■ MTcell MFgetVar ( char* ident ) 

MFgetVar returns the value of the MuPAD variable named ident. If this variable was 
not assigned a value, MFgetVar returns the value MCnull. 




98 



Application Programming Interface (MAPI) 



MFdelVar Removes a MuPAD variable 

■ void MFdelVar ( char* ident ) 

MFdelVar removes respectively unaissigns the MuPAD variable named ident. 

MFsetVar Assigns a MuPAD variable a value 

■ void MFsetVar ( char* ident, MTcell value ) 

MFsetVar assigns the MuPAD variable named ident the object value. The argu- 
ment value is not copied by MFsetVar. 



Examples 

• The function vartest sets, reads-out and deletes the MuPAD variable aTest. 



» read ( "Makemod" ) ( "exa060803a" ) : 
MFUNC( vartest, NCnop ) 


// function * vartest^ 


{ MTcell number = MFlongC 42 ); 


// create a DGM_INT 


MFsetVarC "aTest", number ); 


// sets ^ aTest ^ to 42 


MTcell t=MFgetVar( "aTest" ); 


// reads-out its value 


MFdelVarC "aTest" ); 


// unassigns ^ aTest ^ 


MFreturnC t ) ; 


// returns 42 


} MFEND 

» aTest: =666: 

aTest, vartest 0, aTest; 

666, 42, aTest 





6.9 Arbitrary Precision Arithmetic 

MAPI provides a direct interface for doing fast arbitrary precision arithmetic. 
Refer to section 4.5.4 to read about numerical data types supported by MAPI. 

For more complex operations as well as for symbolic computations the cor- 
responding MuPAD built-in and library functions (refer to the MuPAD User’s 
Manual [50] for additional information) can be called by use of routine MFcall. 

All MAPI arithmetic routines described in this section expect pure MuPAD 
numbers as their arguments (objects for which the routine MFisNumber returns 
true). They cannot operate on any symbolic expressions! 

The routines described here are subdivided according to the following categories: 
basic arithmetic, transcendental and algebraical routines and special routines. 
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6.9.1 Basic Arithmetic 

The following routines provide an interface to the basic arithmetic for arbitrary 
precision numbers in Mu PAD. 



MFadd Adds two numbers 

■ MTcell MFadd ( MTcell s, MTcell t ) 

MFadd returns the sum s + t. MFadd frees the numbers s and t. 



MFaddto Adds two numbers 

■ void MFaddto ( MTcell* s, MTcell t ) 

MFaddto computes s:= s + t. MFaddto frees the number t. 



MFmult Multiplies two numbers 

■ MTcell MFmult ( MTcell s, MTcell t ) 

MFmult returns the product s * t. MFmult frees the numbers s and t. 



MFmult to Multiplies two numbers 

■ void MFmultto ( MTcell* s, MTcell t ) 

MFmultto computes s:= s * t. MFmultto frees the number t. 



MFdec Decrements a number 

■ MTcell MFdec ( MTcell* s ) 

MFdec decrements the number *s. 



MFdiv Divides two numbers 

■ MTcell MFdiv ( MTcell s, MTcell t ) 

MFdiv returns the quotient s / t. MFdiv frees the numbers s and t. 



MFdivto Divides two numbers 

■ void MFdivto ( MTcell* s, MTcell t ) 

MFdivto computes s:= s / t. MFdivto frees the number t. 



MFdivInt Integer division of two numbers 

■ MTcell MFdivInt ( MTcell s, MTcell t ) 

MFdivInt returns the integer part of s/t. MFdivInt frees the numbers s and t. 
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MFinc Increments a number 

■ MTcell MFinc ( MTcell* s ) 

MFinc increments the number *s. 



MFmod Computes the positive modulus of two numbers 

■ MTcell MFmod ( MTcell s, MTcell t ) 

MFmod returns the positive value s mod t. MFmod frees the numbers s and t. 

MFmods Computes the symmetrical modulus of two numbers 

■ MTcell MFmods ( MTcell s, MTcell t ) 

MFmods returns the value s mod t, where the result may be negative. MFmods frees 
the numbers s and t. 



MFpower Computes the power of two numbers 

■ MTcell MFpower ( MTcell s, MTcell t ) 

MFpower returns the value s^. MFpower frees the numbers s and t. 



MFsub Subtracts two numbers 

■ MTcell MFsub ( MTcell s, MTcell t ) 

MFsub returns the difference s - t. MFsub frees the numbers s and t. 



MFsubtO Subtracts two numbers 

■ void MFsubtO ( MTcell* s, MTcell t ) 

MFsubtO computes s:= s - t. MFsubto frees the number t. 

6.9.2 Transcendental and Algebraical Functions 

The following routines provide an interface to a selection of transcendental and 
algebraical functions for arbitrary precision numbers in Mu PAD. 

MFbinom Binomial coefficient of two numbers 

■ MTcell MFbinom ( MTcell s, MTcell t ) 

MFbinom returns the binomial coefficient (^). It frees the numbers s and t. 
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MFexp Exponential function 

■ MTcell MFexp ( MTcell s ) 

MFexp returns the value e®. MFexp frees the number s. 



MFgcd Computes the gcd of two numbers 

■ MTcell MFgcd ( MTcell s, MTcell t ) 

MFgcd returns the greatest common divisor. MFgcd frees the numbers s and t. 



MFlcm Computes the 1cm of two numbers 

■ MTcell MFlcm ( MTcell s, MTcell t ) 

MFlcm returns the least common multiple. MFlcm frees the numbers s and t. 



MFln Natural logarithm 

■ MTcell MFln ( MTcell s ) 

MFln returns the natural logarithm ln(s). It behaves like the MuPAD function In 
[50]. MFln frees the number s. 



MFsqrt Computes the square root of a number 

■ MTcell MFsqrt ( MTcell s ) 

MFsqrt returns the square root of the number s. It behaves like the MuPAD function 
sqrt [50]. MFsqrt frees the number s. 

6.9.3 Special Functions 

The following routines provide special operations on MuPAD numbers: 



MFabs Absolute value of a number 

■ MTcell MFabs ( MTcell s ) 

MFabs returns the absolute value of the number s. s may be a complex number. 

MFabs frees the number s. 



MFisNeg Checks if a number is negative 

■ MTbool MFisNeg ( MTcell s ) 

MFisNeg returns true if s is negative. Otherwise it returns false. 
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MFneg 

■ MTcell MFneg ( MTcell s ) 

MFneg negates the number s. MFneg frees the number s. 



Negates a number 



MFrec Reciprocal value of a number 

■ MTcell MFrec ( MTcell s ) 

MFrec returns the reciprocal value of the number s. MFrec frees the number s. 



Examples 

• The function arithl returns the negated sum of two given numbers. 



» readC'Makemod") ("exa060900a") : 

MFUNC( arithl, MCnop ) // function ^ arithl^ 

{ MFnargsCheckC 2 ); // expects two args 

MFargCheck(l,MCnumber) ; // both arguments 

MFargCheck(2,MCnumber) ; // must be numbers 

MTcell s=MFcopy(MFarg(D), t=MFcopy(MFarg(2) ) ; 

MFreturnC MFneg(MFadd(s ,t) ) ); // returns -(s+t) 

} MFEND 

» arithl (3, 5) ; 



The function det2 returns the determinant of a given 2x2 matrix. 



» read ( "Makemod" ) ( "exa060900b" ) : 

MFUNC( det2, MCnop ) 

{ MFnargsCheckC 1 ) ; 

MFargCheck ( 1 , DOM.ARRAY ) ; 

if( MFdimArrayCMFargCD) != 2 ) 

MFerrorC "Bad matrix dimension." 
MTcell l=MFarray21ist(MFarg(D) ; 
MTcell u=MFmult( MFcopy(MFop(l,0)) , 
MTcell v=MFmult( MFcopy(MFop(l,2)) , 
MFfree(l); 

MFreturnC MFsubCu,v) ); 

} MFEND 



// function ^det2^ 

// accepts one arg. 

// which is an array 
// dim. must be two 

); 

// converts to a list 
MFcopyCMFopCl,3)) ); 
MFcopyCMFopCl,!)) ); 

// returns determinant 



» A:=arrayCl . .2, 1 . .2, [[3,9] , [3,23]] ) : det2CA); 
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6.10 Miscellaneous 

This section describes routines and variables for displaying data, allocating 
memory blocks without using MAMMUT [30] and managing the Mu PAD kernel 
and dynamic modules. It also introduces essential MAPI constants and data 
type definitions which are needed when writing module functions. 



6.10.1 Displaying Data 

Mu PAD objects of the C/C++ data type MTcell can be displayed using the 
routine MFout. To display basic C/C++ data types, the routines MFputs and 
MFprintf are provided. They behave like the corresponding C standard routines 
but display their output in the Mu PAD session window respectively the corres- 
ponding output region of the notebook. Since Mu PAD objects can be converted 
to C/C++ character strings by use of routine MFexpr2text, MFprintf may also 
be used for displaying Mu PAD data as formatted text. 

To print data into files, the C standard routine fprintf as well as the Mu PAD 
built-in function f print [50] -refer to MFcall- can be used. 



MFout Displays a MuPAD object 

■ MTcell MFout ( MTcell object ) 

MFout displays the MuPAD value object within the current output region of the 
MuPAD session window and returns it as the return value. The return value object 
is not copied by MFout. 



MFprintf Displays C/C++ data 

■ void MFprintf ( char* format, . . . ) 

MFprintf displays the character string format and the C/C++ data represented by 
”...” within the current output region of the MuPAD session window. It behaves 
similar to the C/C++ standard routine printf . Since MFprintf uses a static buffer, 
output size is limited to 1024 characters. 



MFputs Displays a C/C++ character string 

■ void MFputs ( char* string ) 

MFputs displays the C/C++ character string string within the current output region 
of the MuPAD session window. This routine behaves similar to the C/C++ standard 
routine puts. 
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Examples 

• The function showme demonstrates the usage of MAPI output routines. 



» read ( "Makemod" ) ( "exa06100 la" ) : 

MFUNC( showme, MCnop ) // function ^showme* 

{ MFnargsCheckC 1 ); // accepts one argument 

MTcell a=MFarg( 1 ); // gets first argument 

if (MFisInt(a)) MFprintf ("'/.ld\n" ,MFlong(a) ) ; // prints a Uong* 
else if (MFisString(a)) MFputs(MFstring(a)) ; // prints a string 
else MFoutC a ) ; // prints an object 

MFreturnC MFcopy(MVnull) ) ; // returns *null()* 

} MFEND 

» showme(13), showme("any string"), showme ( 7/666 ) ; 

13 

any string 
7/666 



6.10.2 Allocating Memory 

Refer to section 4.4 for a brief introduction to the memory management of 
Mu PAD. Memory blocks which are no Mu PAD cells (MTcell) should be allocated 
and de- allocated with the following platform independent MAPI routines. 



MFcfree Frees a memory block 

■ void MFcfree ( void* pointer ) 

MFcfree frees the memory block addressed by pointer. It behaves like the C/C++ 
standard routine free. MFcfree must be applied only to memory blocks al- 
located by MFcmalloc. 



MFcmalloc Allocates a memory block 

■ void* MFcmalloc ( MTcell length ) 

MFcmalloc allocates a memory block of length bytes. It behaves like the C/C++ 
standard routine malloc. Memory blocks allocated by MFcmalloc must be 
deallocated by use of routine MFcfree. 

Examples 

• Function hrule(l,c) constructs a MuPAD string which consists of the char- 
acter c concatenated 1 times. Also refer to example exa060702b on page 77. 
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» readO’Makemod") ("exa06 1002a") : 

MFUNC( hrule, MCnop ) 

{ MFnargsCheck( 2 ) ; 

MFargCheckC 1, D0M_INT ); 
MFargCheck( 2, DOM^STRING ); 
long l=MFlong ( MFarg(l) ); 
char *s=MFstring( MFarg(2) ) ; 
char *t=(char*) MFcmalloc( 1+1 ) 
t[l] = ’\0^ 

while(l>0) tC — l]=s[0]; 

MTcell r=MFstring(t) ; 

MFcfree(t) ; 

MFreturn( r ) ; 

} MFEND 



// function ^ hrule ^ 

// accepts two arguments 
// an integer (length) 

// a string (character) 
// gets length 
// gets character 
// allocates new string 
// terminates the string 
// fills the string 
// converts to MuPAD 
// frees the C buffer 
// returns new string 



print ( hrule (7, "=")." ok " .hrule(7,"=") ): 
======= ok ======= 



6.10.3 Kernel and Module Management 

The following routines enable the user to access and control essential kernel and 
module features. 



MCmodule Name of the current module domain 

■ char* MCmodule 

MCmodule contains the name of the module domain in which the current module 
function is defined. This C/C++ character string is defined by the module generator. 
Also refer to MVdomain and MVdomkey. 



MFdisplace Displaces a module 

■ long MFdisplace ( ) 

MFdisplace displaces a module with respect to the method Least Recently Used. The 
routine returns zero if it was successful and an error code unequal to zero otherwise. 



MFglobal Declares a global MuPAD variable 

■ void MFglobal ( MTcell* var ) 

MFglobal declares the C/C++ variable specified by the address var as a global 
variable of the MuPAD memory management. This information is propagated to the 
garbage collector to prevent it from freeing the contents of *var. Writing modules, 
MFglobal should be applied to each global variable of type MTcell. Also refer 
to section 7.3 and the example given in appendix 10.6.3. 
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MFstatic Changes the module attribute ’static’ 

■ MTbool MFstatic ( char* name, long mode=l ) 

If mode is zero, MFstatic sets the module attribute static of module name to false. 
Otherwise the attribute is set to true. If the routine fails it returns false. Otherwise 
it returns true. 



MFterminate Terminates the MuPAD Kernel 

■ void MFterminate ( ) 

MFterminate terminates the MuPAD kernel by making a complete kernel shutdown, 
i.e. terminating the memory and module manager, calling the user-defined shutdown 
functions specified with Pref : :callOnExit, etc. 



MFuserOpt Returns the string of user kernel options 

■ char* MFuserOpt ( ) 

MFuserOpt returns the string of MuPAD kernel options specified with the UNIX com- 
mand line option -U option. If no option was specified in this way, the routine 
returns an empty string. Also refer to Pref: :userOptions [50]. 



Examples 

• Function disptest displays the name of its module and displaces as many 
currently loaded modules as possible. 



» read("Makemod") ("exa061003a") : 






MFUNC( disptest, MCnop ) 




// function ’disptest* 


{ MFprintfC "Module ’*/,s^:\n", 


MCmodule ) ; 


// displays its name 


while ( MFdisplaceO == 0 ) 




// displaces modules 


MFputsC "Displacing a module" ); 


// as many as possible 


MFreturn( MFcopy(MVnull) ); 
} MFEND 




// returns ’nullO’ 


» module ( stdmod ) , module ( slave ) , 

Module »exa06 1003a ^ 
Displacing a module 
Displacing a module 
stdmod, slave 


disptest 0 ; 





• The function sflag sets the attribute static for its module and nosflag 
removes it. Since the original output is long, it was cut in the example below: 
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» readC'Makemod") ("exa06 1003b") : 




MFUNC( sflag, MCnop ) 


// function ^ sflagO sets 


{ MTbool ok=MFstatic(MCmodule, 1); 


// the attribute ’static^ 


MFreturn( MFbool(ok) ); 
} MFEND 


// returns a Boolean ’ok^ 


MFUNC( nosflag, MCnop ) 


// ’nosflag’ removes 


{ MTbool ok=MFstatic(MCmodule, 0); 


// the attribute ’static’ 


MFreturnC MFbool(ok) ); 
} MFEND 


// returns a Boolean ’ok’ 


» sflagO, module: : statO , nosflagO, module: : stat() ; I 


. . . exa061003b: age= 0 I flags = {" 


static"} . . . 


. . . exa061003b: age= 0 I flags = {} 
TRUE, TRUE 





• The following module initializes a C/C++ variable which is gobal to the whole 
module code. This task is done by the module initialization function initmod 
when loading the module by use of function module. The function globtest 
returns the contents of this variable. 



» readC'Makemod") ("exa061003c") : 




static MTcell value; 


// a global variable 


MFUNC( initmod, MCstatic ) 

{ MFglobal ( ftvalue ); 
value = MFlongC 42 ); 
MFreturnC MFcopy(MVnull) ); 
} MFEND 


// function ’initmod’ 

// declares as global 
// and initializes it 
// returns space object 


MFUNCC globtest, MCnop ) 

{ MFreturnC MFcopyC value) ); 
} MFEND 


// function ’globtest’ 
// returns ’value’ 


» globtest C), globtest C), globtest C), 


globtest C) ; 


42, 42, 42, 42 





If you remove MFglobal (&value) , Mu PAD may print out obscure error messages 
due to the fact, that the contents of value may have been freed by the garbage 
collector. 

Also note, that this module (respectively initmod) is declared as static (refer 
to section 4. 7. 1.2) to prevent the module manager from displacing it. Otherwise 
the module may loose the contents of value. 
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6.10.4 Constants and Data Type Definitions 

6.10.4.1 Data Type Definitions 

When implementing modules, besides the basic data types of the C/C++ pro- 
gramming language also the following Mu PAD data type definitions are needed. 



MTbool Internal data type for C/C++ Booleans 

■ MTbool 

The data type MTbool declares an internal Mu PAD Boolean. This can be either one 
of the constants listed in section 6.10.4.5 when using the 3-state logic or the value 0 
(false) respectively any value ^ 0 (true) when using a 2-state logic. 



MTcell Internal data type of a MuPAD memory cell 

■ MTcell 

The data type MTcell declares a cell respectively a tree of the MuPAD memory 
management. Read section 4.4 for more detailed information. 

6.10.4.2 Meta Types 

The following data type declarations unite some MuPAD basic domains (see 
table 4.1) into meta types to make programming more convenient. 



MCchar Meta Data Type: character based types 

■ int MCchar 

MCchar includes the basic domains D0M_IDENT and D0M_ STRING. Read section 4.5 for 
details about MuPAD data types. 



MCinteger Meta Data Type: integer numbers 

■ int MCinteger 

MCinteger includes the basic domains D0M_INT and DOM-APM. Read section 4.5 for 
details about MuPAD data types. 



MCnumber Meta Data Type: any numbers 

■ int MCnumber 

MCnumber includes the meta type MCinteger and the basic domains D0M_C0MPLEX, 
DOM-FLOAT and D0M_RAT. Read section 4.5 for details about MuPAD data types. 
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6.10.4.3 Module Function Attributes 

Module functions may carry attributes which control their behaviour at load 
and run-time or define special properties. Read section 6.2 for examples and 
information about using these attributes. 



MChidden Module function attribute: hidden function 

■ int MChidden 

MChidden prevents the module manager from inserting the name of this module func- 
tion into the module interface. However, the function can be directly executed by 
the user. Furthermore, this module function will not be exported as a global object 
when using the export [50] command. 



MChold Module function attribute: option hold 

■ int MChold 

MChold prevents the module function from evaluating its function arguments. It 
behaves as option hold which can be set for Mu PAD procedures. Refer to example 
exa060200c on page 58. 



MCnop Module function attribute: no option 

■ int MCnop 

MCnop (no option) is the neutral function attribute which is set by default. Refer to 
example exa060200a on page 58. 



MCremember Module function attribute: option remember 

■ int MCremember 

MCremember activates the caching of results for this module function. Previously 
calculated results are not recalculated, but are read-out from the so-called remember 
table of this function. MCremember behaves as option option remember which can be 
set for Mu PAD procedures. Refer to example exa060200b on page 58. 



MCstatic Module function attribute: static function 

■ int MCstatic 

MCstatic declares a module function as static, meaning its machine code cannot 
be displaced automatically. Also refer to section 4.7. 1.2 and the routine MFstatic 
demonstrated in example exa06 1003b on page 106. 
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6.10.4.4 The Copy and Address Attribute 

For some MAPI routines the following attributes control whether a reference 
to an object itself or a copy of it is returned. 



MCaddr Copy mode: address 

■ int MCaddr 

If the attribute MCaddr is passed to a MAPI routine, it instructs the routine to 
return a reference to an object instead of a copy. At time MCaddr can be used with 
the routines MFident and MFstring. Refer to the corresponding documentation. 



MCcopy Copy mode: copy 

■ int MCcopy 

If the attribute MCcopy is passed to a MAPI routine, it instructs the routine to return 
a copy of an object instead of a reference. At time MCcopy can be used with MFident 
and MFstring. Also refer to MCaddr as well as to example exa060702b on page 77. 

6.10.4.5 Internal Boolean C/C++ Constants 

With the 3-state logic, Mu PAD uses the following C/C++ constants for the 
internal representation of the Boolean values. 



MCf alse Internal Boolean C/C-I-+ constant: false 

■ MTbool MCfalse 

MCfalse represents the internal MuPAD Boolean FALSE when using a 3-state logic. 
Also refer to MTbool and MFboolS. 



MCtrue Internal Boolean C/C++ constant: true 

■ MTbool MCtrue 

MCtrue represents the internal MuPAD Boolean TRUE when using a 3-state logic. Also 
refer to MTbool and MFboolS. 



MCunknown Internal Boolean C/C-1— h constant: unknown 

■ MTbool MCunknown 

MCunknown represents the internal MuPAD Boolean UNKNOWN when using a 3-state 
logic. Also refer to MTbool and MFboolS. 
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6.10.4.6 Empty MuPAD cell 

For the MuPAD memory management MAMMUT [30, refer to MMMNULL], the 
so-called empty cell MCnull has a similar meaning as the NULL pointer for the 
standard C/C4-+ memory management. It is a cell of no space which is used 
to indicate an initialized but empty object. 

Some MAPI routines use MCnull to indicate that they failed, e.g. the routine 
MFgetTable. Do not mix up MCnull with the space object MVnull of the basic 
domain D0M_NULL. 



MCnull Empty MuPAD object 

■ MTcell MCnull 

MCnull represents the empty MuPAD cell. It can be used internally to initialize the 
children of MuPAD cells or to indicate that an action failed. No other MAPI 
routines than MFfree, MFequal and MFout must be applied to MCnull. MCnull 
must not be returned by a module function. 



Examples 

• The function donothing demonstrates the usage of the empty cell MCnull. 



» read("Makemod")("exa061004a") : 

MFUNC( donothing, MCnop ) 

{ MTcell value=MCnull ; 

MFout ( value ) ; 

MFfree ( value ); 
value=MFgetVar("gandalf ") ; 
if( MFequal (value, MCnull) ) 
MFreturnC MFcopy (MVnull) ); 
} MFEND 

» donothingO; 

gandalf is undefined 



// function ^donothing’ 
// the empty MuPAD cell 
// can be displayed and 
// can be freed n-times 
// reads-out ’gandalf* 
MFputs( "gandalf is undefined" ); 

// returns space object 



release 1.4 MCnull is defined as the NULL pointer of type MTcell but this may change 
in future versions. 




7. Special features 



This chapter gives additional information about features of Mu PAD and the 
module interface, which may be useful for special applications. For detailed 
information about online documentation for modules, read section 2.4 and 3.4. 



7.1 Module Initialization Function 

The module function initmod is automatically executed when loading a module 
with the command module respectively loadmod. It can be used to initialize 
the module -e.g. to set global values-, to display protocol messages, etc. As any 
other module function, initmod must return a valid MuPAD object. 



Examples 

• This example demonstrates the usage of the module domain method initmod. 



» readC'Makemod") ("exaOTOlOOa") : 




MFUNC( initmod, MCnop ) 


// function ’initmod’ 


{ MFprintfC "Module is ready. \n", 


MCmodule ) ; 


MFreturnC MFcopy(MVnull) ); 


// returns dummy value 


} MFEND 




» inf o(exa070100a) : 




Module ’exa070100a’ is ready. 




Module: ’exa070100a’ created on 23. Feb 


.98 by mmg R- 1.4.0 


Refer to the Dynamic Modules User’s Manual for MuPAD 1.4 | 
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7.2 Including MuPAD Code 

Since modules as well as library packages both are organized as domains, it is 
possible to include MuPAD code into a module domain. For a module mod, this 
can simply be done by creating a text file mod. mdg, placing it into the same 
directory as the binary mod. mdm. mod. mdg must have the following format: 

table( "include*' = [ 

stringi = expri , ... 

] ): 

When the module is loaded by use of function module, the expressions expri 
are inserted into the module domain and can be accessed later as mod : : stringi. 
Note that mod. md^ should not contain any other data than listed above, except 
comments. It is read-in by use of function read before the module domain is 
created, but the expressions expri are inserted into the module domain after all 
module functions were inserted. Thus the table is evaluated once -by read- but 
cannot access entries of its own module domain. 

7.2.1 Module Procedures 

The methods and axioms listed above are called module procedures respectively 
module expressions and can be used as usual domain entries. They can be 
defined in a more convenient way by including them into the module source 
code using the following syntax: 

MPR0C( name = ) or MEXPR( name = ) 

Note that the character string ”. . .” must contain a valid expression, given in 
the MuPAD programming language. The character " must be written as \" 
when used in this string. Using the keyword MPROC, a module procedure is 
automatically inserted into the interface of the module domain. 



7.2.2 Hybrid Algorithms 

This technique supports the development of so-called hybrid algorithms which 
consist of a combination of C/C+-h routines and MuPAD procedures and ex- 
pressions. Whereas C/C++ code should be used for time relevant subroutines, 
procedures can be used to handle complex mathematical data, which may be 
a bit difficult on a C/C++ level. Module procedures are also an appropriate 
method to separate parts of an algorithm which are to be run-time configurable 
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or exchangable by the user. In fact, all not time relevant parts may be imple- 
mented as module procedures, because using the Mu PAD high-level language is 
often more convenient. 

As described in section 7.3, module expressions may be used to store a global 
state of a non-static dynamic module. 

Examples 

• The module procedure negrec negates its argument and calls the module 
function dorec to compute the reciprocal value. Function initmod is defined 
as a procedure and the module domain entry value is set to 42. 



» readC’Makemod") ('•exa070200a") : 

MPR0C( initmod="fun( (print (\"Module *exa070200a^ is ready.X")))" ) 
MPR0C( negrec ="proc(x) begin exa070200a: :dorec(-x) end_proc" ) 
MEXPR( value ="42" ) 

MFUNC( dorec, MCnop ) // function ^ dorec’ 

{ MFnargsCheckC 1 ) ; // accepts one argument 

MFargCheckC 1, MCnumber ); // which is a number 

MFreturnC MFrec(MFcopy(MFarg(l) ) ) ); 

} MFEND 

» negrec(7), negrec(exa070200a: : value) ; 

"Module ’exa070200a’ is ready." 

- 1/7, -1/42 



Another example of module procedures is given in section 10.6.3. Also refer to 
section 5.1.3 for additional information concerning the module generator. 



7.3 Storing a Global State 

Global states of a module can be stored in C/C-f-h variables of the module. 
Note that a global variable of type MTcell must be declared as global to the 
Mu PAD memory management, to prevent the garbage collector from freeing its 
contents. This can be done with the routine MFglobal. 

When a module is displaced (see section 4.7.2), the contents of all its C/C+-h 
variables gets lost. This may not be acceptable when working with open files 
or network connections. To avoid automatical displacement of the module, it 
can be declared as static at compile time. Refer to section 4.7.1 for details. 

On the other hand, if the module code is huge and seldom used it should be 
possible to displace its machine code in order to save system resources. This 
can be achieved using one of the methods discussed in the following sections. 
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7.3.1 Using Module Domain Entries 

If the value of a global state can be converted into a Mu PAD object, it may be 
stored in the module domain -see section 7.2.1- using the routines MFinsDomain 
and MFgetDomain. Refer to section 6.7.10 for details. 

Even if the module code in displaced, the module domain and its domain entries 
still exist and allow to reload the machine code on demand. The module domain 
is removed only when calling the function reset or when assigning the identifier 
which stores this domain a new value. Module expressions may get lost when 
applying the function module respectively loadmod to the module, because it 
reinitializes the module domain. 

7.3.2 Temporary Static Modules 

The routine MFstatic allows to change the static attribute of a module at 
run-time. This enables the user to control whether the module is currently 
allowed to be displaced or not. 

For example, using a module for interprocess communication, its state must 
only be saved while a connection is open. When all connections are closed, 
the module may be displaced without losing relevant information. This can be 
achieved using the routine MFstatic to lock the module whenever a connection 
is opened and to unlock it when all connections are closed. 



Examples 

• exa070200a: demonstrates how to define module expressions, p. 115 

• exa060710b: demonstrates the access to module domain entries, p. 91 



7.4 User-defined Data Types 

The domains concept [7] allows users to create their own Mu PAD data types. 
The usual way of creating a new type my data is to define a domain mydata 
and procedures like mydata: :new for creating elements, mydata: : print for 
displaying them, mydata: :expr to convert them into Mu PAD expressions -as 
far as possible- and so on. 

Since modules are represented as domains, they can also be used to implement 
user-defined data types. Instead of Mu PAD procedures, here, module functions 
may be used to define methods for creating and operating on the elements. 
For information about the domain representation of modules as well as special 
domain methods refer to section 2.3 and section 3.3. 
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For general information about writing library packages and implementing user- 
defined data types refer to the paper Writing library packages for MuPAD [9]. 



Examples 

Refer to the following examples which demonstrate how user-defined data types 
can be implemented in MuPAD using dynamic modules: 

• stack: a simple example, demonstrates the general concept, section 10.2.1 

• mf p: quick & dirty, using machine floating-point numbers, section 10.2.2 



7.5 MuPAD Preferences 

The domain Pref [50] allows the user to get and set preferences of the MuPAD 
system. The following preferences are relevant to module programmers. Refer 
to the online documentation of MuPAD release 1.4.1 for the complete list. 

Pref : : callBack: The function, respectively the list of functions, specified 
here are executed periodically. For example, this feature can be used 
to check a status, to display protocol messages or close files or network 
connections used by a module periodically. Note that callback routines 
must be used very carefully, especially if they have any side-effects like 
changing or removing global values! 

Pref : : callOnExit: The function, respectively the list of functions, specified 
here are executed when (directly before) the MuPAD kernel is terminated. 
This can be used for any kind of re-initialization, e.g. closing files or 
network connections or freeing other resources used by a module, etc. 
Refer to the module net (section 10.6.3), which provides the so-called 
MuPAD macro paralellism, as an example. 

Pref: :moduleTrace: This is a debugging feature for wizards. The MuPAD 
kernel objects used by a module -i.e. their kernel entry codes- are displayed 
at run-time when this preference is set to TRUE. 

Pref : :userOptions: Contains user options which were passed to the MuPAD 
kernel when it was started. On UNIX systems, this preference is set to the 
string '*xxx yyy" when calling mupad -U ^xxx yyy^ respectively xmupad 
-U ^xxx yyyC Refer to the module net (section 10.6.3), which provides 
the so-called Mu PAD macro paralellism, as an example. 




8. Technical Information 



8.1 Supported Operating Systems 

The complete list of operating systems for which dynamic modules were imple- 
mented is given in table 5.2. Due to technical reasons -e.g. compiler changes, op- 
erating system updates, the hardware platforms available to the Mu PAD group 
at the University of Paderborn, etc-, some platforms may not be supported with 
new Mu PAD releases. 



8.1.1 Apple Macintosh 

Dynamic modules can be supported for PowerPC systems using Apple System 
7 or newer only. They will be made available soon. Please contact the Mu PAD 
developers^ for information about the current state. Since creation of modules 
differs slightly from the method demonstrated for UNIX operating systems, 
this, as well as special features of the Macintosh version, will be described in a 
separate documentation. 



8.1.2 Windows 95/NT 

Dynamic modules for Windows 95/NT will be made available with MuPAD Pro 
soon. Please contact the MuPAD developers^ for information about the current 
state. Since creation of modules differs slightly from the method demonstrated 
for UNIX operating systems, this, as well as special features of the Windows 
95/NT version, will be described in a separate documentation. 



^The author andiSmupad.de or bugsSmupad.de. 
^The author andiSmupad.de or bugsSmupad.de. 
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8.1.3 Linux 

Dynamic modules for Linux are supported with Linux/ELF systems (Linux 
kernel release 2.0 or higher). Since Linux is a UNIX operating system, please 
refer to section 8.1.4 for additional information. 



8.1.4 Unix 

The UNIX derivatives for which dynamic modules were implemented yet are 
listed in table 5.2. Further ports are made according to their need. Contact the 
Mu PAD developers^ for detailed information. 

Though the following information is related to UNIX operating systems, many 
statements are also valid for other operating systems. Even if the methods and 
the syntax may differ. 



8.2 Integrating Software Packages 

8.2.1 Shared Libraries 

If a software package is available as a shared library -often called a dynamic 
library-, it can simply be linked to and directly be used within a dynamic module 
as described in section 8.5.2. 

You may have problems if this library was compiled from other programming 
languages than C-h+. Refer to section 8.4 for information about integrating 
such kinds of libraries into dynamic modules. 

A demonstration of integrating a shared library into a dynamic module is given 
by the example IMSL described in section 10.3.1. 

8.2.2 Static Libraries 

If a software package is available as a static library archive, the possibility to 
integrate it into a dynamic module depends on the way it was compiled and 
which compiler will be used by mmg to create the module binary. In the best 
case, it can simply be used in the same way as shared libraries (read section 

8.5.2 for detailed information) but in contrast to them, it becomes an integral 
part of the module binary. Thus, there will be no need to set any library search 
path (see section 8.5.1). 



^The author andiSmupad.de or bugsSmupad.de. 
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You may have problems if this library was compiled from other programming 
languages than C++. Refer to section 8.4 for information about integrating 
such kinds of libraries into dynamic modules. 

You may also have problems if this library was not compiled into so-called 
position independent code. Refer to section 8.3 for detailed information. 

A demonstration of integrating a static library archive into a dynamic module 
is given by the integration of NAGC algorithms (see section 10.3.2) as well as 
by the module net (section 10.6.3) which uses the PVM library. 

8.2.3 Source Code 

If a software is available as C/C++ source code, it can be compiled to so-called 
position independent code (PIC) using a C++ compiler, e.g. the GNU g++ 
compiler using option -fpic. Read section 8.3 for detailed information about 
position independent code. 

If the source code uses any routines, variables or other definitions of the Mu PAD 
kernel, it must be compiled using the module generator mmg with option -c. 
Refer to section 5.2.3 for detailed information. 

If the source code was written in any programming language other than C++, 
a corresponding compiler must be used to compile it either into a shared library 
or into a static library archive (respectively an object file) of position independ- 
ent code. Refer to section 8.3 and section 8.4 for detailed information about 
integrating such kind of object code. 



8.3 Position Independent Code 

Due to the fact that a dynamic module is loaded at run-time, most operating 
systems and compilers respectively linkers expect that it has been compiled 
into so-called position independent code (PIC). This allows the dynamic linker 
to place it at any address of the memory space of the Mu PAD kernel process 
and to link it with the kernel object code. 

C++ source code can be compiled to position independent code either using 
the GNU g++ compiler with option -fpic or any other C++ compiler which 
usually accept options like -pic or -Kpic. Refer to section 5.2.1 and section 

5.2.3 as well as to your C++ compiler manual for additional information. 

If your compiler manual does not provide any information about creating pos- 
ition independent code explicitly, try to create a shared library and then refer 
to section 8.2.1 for further instructions. 
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Note that depending on your operating system, compiler and linker, you may 
not be able to integrate software packages into dynamic modules if they are not 
compiled to position independent code respectively a shared (dynamic) library. 



8.4 Including Non C++ Code 

Since the Mu PAD module generator mmg (section 5) uses a C++ compiler to 
create module binaries, special tasks have to be carried out for including any 
non C++ code into a dynamic module. 

In general, different compilers may use different naming conventions for symbols^ 
when creating object code. Thus, a linker may not be able to link object code 
files which were created by different compilers. 

Further problems may occur when using different programming languages. They 
often differ in their basic data types, the way of calling subroutines and passing 
arguments and so on. The possibility of linking object code files which were 
compiled from different programming languages strongly depends on the oper- 
ating system as well as the compilers and the linker which are used. 

The following sections describe the usual way to handle these problems on 
UNIX operating systems. However, also refer to the corresponding technical 
documentation of your operating system respectively your compilers and linker 
for detailed information. 



8.4.1 Including K&R-C or ANSI-C Code 

Including plain K&R-C or ANSI-C code, the corresponding C header files must 
be embedded into so-called external statements extern ''C*' {. . .} to instruct 
the C++ compiler to use plain C style linkage for these objects.^ 

In some cases it might be necessary to explicitly link the K&R-C respectively 
the ANSI-C standard library libc.so. This may also require to redefine the 
linker call of the module generator (section 5.2.2) as well as the search path for 
shared libraries (section 8.5.1). Also refer to your C/C++ compiler manual. 

An example of using plain C code within dynamic modules is given in section 
10.3.2, by the integration of the NAGC library. 

^Internal references to machine code routines and variables. 

^C++ compilers use a naming convention and a linkage which is different from K&R-C 
and most ANSI-C compilers. Also refer to a C++ reference manual, e.g. [49, section 4.4]. 
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8.4,2 Including PASCAL Code 

Some C++ compilers and linkers allow to use object code, which was compiled 
from source code written in the PASCAL programming language, within C++ 
binaries. Refer to your PASCAL and C++ compiler manual as well as to a C++ 
reference manual (e.g. [49, section 4.4]) for detailed information. 

In some cases -especially when using PASCAL input /output features- it might 
be necessary to explicitly link the PASCAL standard library libp . so. This may 
also require to redefine the linker call of the module generator (section 5.2.2) as 
well as the search path for shared libraries (refer to section 8.5.1). 

An example of integrating PASCAL code into a module is given in section 10.7.2. 



8.5 Shared Libraries 

In contrast to static libraries, so-called shared (dynamic) libraries are no integral 
part of a program but are linked at run-time. This may require to set a library 
search path to enable the linker to find the library files on the hard disk. 

8.5.1 Library Search Path 

Depending on the local configuration of the operating system, the user may 
need to extend the UNIX environment variable LD_ LIBRARY- PATH -respectively 
SHLIB_PATH on HP-UX systems- to enable the dynamic linker to find shared 
libraries on the hard disk, e.g. the GNU library libg++ . so or any library which 
were explicitly linked by the user. 

The following command extends the library search path by a new directory XXX 
on a Solaris as well as a Linux operating system. If this definition is needed 
permanently, it must be inserted at the end the user’s ~/ . cshrc file.^ 

setenv LD_LIBRARY_PATH ${LD.LIBRARY.PATH> :XXX 

8.5.2 Using Shared Libraries 

Include the C/C++ header files -which belong to the shared library- into the 
module source code and link the library by calling the module generator with 
option “Ixxx, where xxx is the name of the shared library file libxxx .so. Refer 
to section 5.2.2 for additional information. 

^Insert the line export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:XXX into the user’s file 
~/. profile when using sh, ksh or bash instead of the csh or tcsh shell. 
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The shared library will not become an integral part of the dynamic module but 
will be linked at run-time automatically when loading the module. If the library 
cannot be found by the dynamic linker at run-time, then refer to section 8.5.1 
to read about extending the shared library search path. 

The fact that users need to install not only the module itself, but also one 
or more shared libraries, which may furthermore require to extend the shared 
library search path too, may be seen as a disadvantage. 

On the other hand, the shared library can be exchanged without recompiling 
the module code. Furthermore, when running more than one Mu PAD kernels on 
a multi processor machine using shared memory, the code of a shared library is 
only loaded once. It is shared between several programs, with the consequence 
that less memory resources are needed. 



8.6 Analyzing Module Object Code 

In some cases -if any problems occur- it might be useful to analyze the machine 
code and the symbol table of a dynamic module in order to get deeper insight 
about the routines and variables which are defined respectively are to be linked 
from other libraries as well as from the Mu PAD kernel process. For this, as well 
as for debugging modules, the user should know about the names of the C-f- f 
routine representing module functions. 



8.6.1 Internal Names of Module Functions 

The name of the C-f+ routine representing a module function is generated auto- 
matically when defining the routine using the keyword MFUNC. The internal name 
of a function module : :func is MFeval_ modw/e_/wnc, e.g. MFeval_stdmod_which 
represents the module function stdmod: : which. ^ 

This name can be used to set a breakpoint within a module function in order to 
debug it with a C/C-h+ source level debugger. Refer to section 8.7 for detailed 
information about debugging dynamic modules on UNIX operating systems. 



8.6.2 Reading the Symbol Table 

The UNIX standard program nm can be used to examine module binaries. It 
lists all objects (symbols^ routines and variables) which are defined or referenced 
in an executable or object file. This is useful for checking the module code when 

^Do not mix up this name with the symbolic name of the C++ routine as used by the 
compiler and linker, e.g. MFeval_stdmod_which__FP10MMMTheaderllT0. 
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the error message Unresolved symbols is displayed while loading a dynamic 
module or executing a module function. 

The symbolic object names listed by nm can be converted into a more readable 
form with the UNIX command c++f ilt^ 

andi> echo MFprintf FPce | c++filt 

MFprintf (char* . . . ) 

andi> echo MFfree FPlOMMMTheader I c++filt 

MFfree(MMMTheader*) 

where MFprintf FPce and MFfree FPlOMMMTheader are symbolic names of 

C/C++ routines as listed by the program nm. The output shows the proto- 
types of the corresponding C++ routines. The type MMMTheader* is an internal 
representation of the MAPI data type MTcell. 



8.7 Debugging Dynamic Modules 

This section describes the debugging of dynamic modules on UNIX operating 
systems using the GNU debugger gdb, which may also be driven by the XI 1 
user interfaces xddd or xxgdb. However, even if the description concentrates on 
the GNU debuggers, other C/C++ source level debugger which provide similar 
features may be used.. 



8.7.1 Preparing the Module and MuPAD 

To debug a dynamic module the user must ensure, that the module binary 
contains debug information. Furthermore, the source code as well as all by the 
module generator temporarily created source (MMG*.C) and object (*.o) files 
must be readable for the debugger. 

1. Compile the module with the module generator using option -g (section 
5.4.2). This option instructs the C++ compiler to include debugging 
information into the binary code and also prevents mmg from removing 
the temporarily created files. 

2. MuPAD must be started in the directory which contains the module source 
code, the files temporarily created by mmg as well as the binary file * .mdm. 
Otherwise the debugger may not find all of the information it needs. 

^This program is distributed with some C-f-f compilers. 
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8.7.2 Stcirting the Debugger 

Note, that for obvious reasons the Mu PAD kernel itself cannot be debugged by 
the user. Due to this fact, it does not make sense to start it directly under 
control of a debugger, because no debug information would be found. 

On the other hand, UNIX debuggers can be attached to a running process if 
the corresponding process-id is known. This feature provides highest flexibility 
and is used to debug dynamic modules in Mu PAD. 

To debug a dynamic module, the debugger can either be started explicitly by the 
user -as described below- or automatically if any fatal error occurs at run-time. 
Refer to section 10.1.7 for detailed information about this features. 

8.7.2. 1 Debugging - Step-by-Step 

The following source file demo . C defines a module function demo : : buggyf unc 
which has a fatal error (an assignment to a NULL pointer) in the source line 4: 

1 HFUHCC buggyf unc, HCnop ) 

2 { MFputsC "I am a buggy module function" ); 

3 char *pnt = lULL; 

4 *pnt = // nice try! 

5 HFreturnC HFcopy(HVnull) ); 

6 } MFEITD 

Below, the debugging of the module function demo : : buggyf unc is demonstrated 
on a Solaris operating system. On other UNIX operating systems, step 2 differs 
in the arguments of the commands ps and grep.^ 

1. Make sure the module is ready for debugging (refer to section 8.7.1). 

andi> mmg -g demo.C 
andi> Is *dGmo* 

MMGdemo.C demo.C demo.mdm demo.o 

2. Start MuPAD and determine the kernel process-id. This can be 
done by use of the UNIX commands ps and grep. Here, the kernel process- 
id is 27821. Load the dynamic module as usual. 

andi> ps -efa I grep solaris/bin/mupad I grep -v grep 

andi 27821 27815 0 09:13:33 pts/10 0:03 /usr/local/MUPAD/share 

/bin/. ./. ./solaris/bin/mupad -1 /usr/local/MUPAD/share/lib . . . 



^You may need to use ps -guaxw. Exchange Solaris by i386, sgi6, etc. 
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3. Start the debugger and attach it to the Mu PAD kernel process. 
and> gdb mupad 27821 

GDB is free software and you are welcome... 

Reading symbols from /us er/andi/ demo .mdm. . .done . 

0xef6f7920 in _read () 

(gdb) 

4. Set breakpoints within the module and continue the execution of 

Mu PAD with the debugger command CONTINUE. Read in section 8.6.1 
about the names of C++ routines representing module functions. 

(gdb) break MFeval.demo_buggyfunc 

Breakpoint 1 at 0xef501c38: file demo.C, line 1 

(gdb) continue 

Continuing. 

5. Call the module function. The debugger will stop at the top of the 
module function and the code can be debugged as usual. 

» demo: :buggyfunc() ; 



Breakpoint 1, MFeval_demo_buggyfunc (MV_args=0xl72df4, 

MV_prev_f unc=0 , MV_eval_type=0 , MV_exec=0x35155c) 
at demo . C : 1 

1 MFUNC( demo, MCnop ) 

Current language: auto; currently C++ 

(gdb) next 

3 MFputs( "I am a buggy module function" ); 

(gdb) 

6. Stop debugging with the debugger command Quit. It detaches the 
debugger from the Mu PAD kernel process and terminates the debugger. 
Mu PAD will still be running and may be terminated as usual. On the other 
hand, if no fatal errors occured during debugging, further computation can 
be done and step 3 to 6 can be repeated later as often as needed. 

(gdb) quit 

The program is running. Quit anyway (and detach it)? (y or n) y 

Detaching from program: process 27821 

andi> 
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8.7.2. 2 Using Xll the Debugger Frontend xxgdb 

Using the debugger interface xxgdb or xddd (figure 8.1) instead of directly using 
gdb is much more convenient and step 2 and 3 of section 8.7.2. 1 can be carried 
out in a Mu PAD session at any time: just load the dynamic module gdb and 
call its method new as demonstrated below. For details refer to section 10.1.7 
or the online documentation of module gdb. 

» module (gdb) : 

» gdbO; 

» module: :buggyfunc() ; 




File Edit View Program ^mmands SUtus Source 



MFUNCC buggyfunc. MCnop ) 

{ MFputsC "I am a buggy module function" ); 

char *pnt = NULL; 

I *pnt = // nice try! 

MFreturnC MFcopyCMVnull) 3; R,,n 

} MFENO — 



Interrupt 

Step Step! 



Ne^t I Next! 



Cont I Rnish 



():||riain 

Reading symbols from /lib/libm.so.5. . .dc 

^ I ♦ t T r * I /I < I I- I 

on itlviei: fhome/andi/Buch/CDROMUiri^ 



» modulefgdb); — • 

Debugger interface is active. Debugger: 'xxgc Back Fwcf 

» rfiodule(demo): 

» demo tt buggy funcO* Edit Kill 

I am a buggy module function . . . ■ 

Starting debugger,,, 

# PRESS ANY KEY TO CONTINUE AFTER QUITING THE DEBUGGER! # 

# OR PRESS Ctrl-Z TO SUSPEND THE CURRENT MuPAD PROCESS, # 



Cgdb) i 

A Continuing. 



Figure 8.1: Debugging a Dynamic Module using the Debugger xddd 





9. Trouble Shooting 



Due to the fact that linking different complex software packages together into 
one binary file is sometimes not trivial, this chapter provides information about 
important aspects that have to be considered as well as some tips for shipping 
around problems which may occur in rare cases. 

Also refer to section 8.2 for an introduction to the methods of integrating soft- 
ware packages into modules. Read section 8.7 for details on debugging modules 
and see section 5.5 for errors and warnings displayed by the module generator. 



9.1 Naming Conflicts 

Most programmers of complex software packages use their own special naming 
conventions for naming C/C++ routines, variables and so on. Hence, in most 
cases different software packages can be linked together without problems. All 
the same, in some rare cases there may be naming conflicts, especially when 
very general identifier names like debug or overflow were used. 

To avoid naming conflicts with the Mu PAD kernel and the MuPAD application 
programming interface {MAPI)^ do not use the prefixes M?? and M? -especially 
MC, MD, MF, MT and MV- to name any C/C+-f routines, variables and definements. 

However, if any naming conflicts occur, use the following strategy to try to solve 
the problem: 

1. Declare conflicting routines and/or variables as local to the context of one 
software package respectively to one C/C+-f source file. This can be done 
with the C/C-h-|- directive static. Remove the declaration of this object 
from the corresponding header file. 

2. Rename the conflicting objects in one of the software packages. 




130 



Trouble Shooting 



3. Undefine conflicting macros or definements using the preprocessor com- 
mand #undef . This can either be done before or after the header files of 
the corresponding software package is included with #include. 

Especially PARI [4] (see sections 4.2 and 4.5.4) uses some generic or re- 
served names like geos, overflow, un, err, etc which may lead to naming 
conflicts. In many cases, they can be undefined within the module source 
code if needed. Refer to section 10.5.1 as an example. 

9.2 Exceptions and Threads 

Exceptions and threads are still features, which are sometimes handled a bit 
different from one operating system to another as well as by two different com- 
pilers. Therefore, at present they are not ofhcially supported by dynamic mod- 
ules. However, depending on the operating system, the compiler and linker 
which is used to compile the thread source code and the dynamic module, the 
binary may run without problems. An example of a module that uses POSIX 
threads is given in section 10.7.3. 

Note: The Mu PAD kernel 1.4 and PARI [4] (see sections 4.2 and 4.5.4) are not 
thread-safe. Besides, parts of the Mu PAD kernel still consist of K&R C code, 
the kernel does not catch any C-|— h exceptions. 



9.3 Streams and Templates 

Since Mu PAD is available for several platforms using different technologies for 
displaying data, no standard streams like stdout are officially supported by 
dynamic modules. Refer to MFprintf for displaying C/C++ data. 

On some systems templates as well as C++ streams cannot be supported due 
to technical problems with controlling the template linker. If you have prob- 
lems using these techniques, try to replace the compiler and linker call of mmg. 
Refer to section 5.2.1 and section 5.2.2 as well as to your compiler and linker 
manual for additional information. A module application that uses templates 
is demonstrated in section 10.5.1. 



9.4 Signals 

The Mu PAD kernel 1.4 uses signals, e.g. to communicate with its Xll/XView 
frontends: SIGUSRl and SIGUSR2 for hand-shaking, SIGCONT for debugging, etc. 
If a module application also needs to use signals, it may use SIGALRM or SIGURG. 
However, on signal conflicts between the kernel and a module application, the 
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corresponding software package cannot be integrated into Mu PAD by use of the 
concept of dynamic modules, but must be linked via interprocess communication 
or corresponding techniques. An example of a module application that uses 
signals is given in section 10.6.3. 



9.5 Questions and Answers 

This section provides information about typical problems which may occur when 
using and/or writing dynamic modules. Further information is available in form 
of Frequently Asked Questions via the World-Wide- Web at the Mu PAD web site. 
Please refer to http://www.mupad.de/support.shtml if the following questions 
do not cover your problem or the answers do not solve your problem. 

The kernel quits with the message . . .unresolved symbols. . .? Check 
if you have linked all libraries needed for your module. 

Check if any name of a C/C-I-+ routine or variable is misspelled or if a 
C/C+-f routine is called with a wrong type of argument. Refer to section 
8.6.2 for information about reading the symbol table of the module. 

If option -j link is used, check if mmg uses the default compiler to create 
the module binary: remove the option -gnu or -nognu if it is set. 

If any non-C-h+ code was linked into the module, check if it was embedded 
correctly. Refer to section 8.4 for details. 

The kernel quits with an error message ...relocation error... or 
. . .symbol not found. . .? See above. 

The kernel quits with a segmentation fault? If the module contains an 
interrupt handler then check if this module was declared as static. Refer 
to section 4. 7. 1.2 and 5.4.1 as well as the routine MFstatic for details. 

If the module stores global states or status information in C/C+-I- vari- 
ables then check if this module was declared as static. 

If a global variable is of type MTcell then make sure it is declared as 
global by use of routine MFglobal. 

Use the dynamic module gdb distributed with the accompanying CD- 
ROM to debug the module. If the error occurs at any point within the 
Mu PAD kernel then either a MAPI routine was called in a wrong way or 
a bad Mu PAD object was created. Typical user errors are e.g. to forget 
to initialize all elements of a list before using it or not to use the routine 
MFcopy when a logical copy of a Mu PAD object is needed. Refer to section 
8.7 and section 10.1.7 for detailed information about debugging. 
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The kernel quits with the message . . .library not found. . .? Check 
if the corresponding library exists and is readable. Check if the library 
search path is set correctly. Refer to section 8.5.1 for details. 

MuPAD dies when unloading a module or on quitting the session? 

Instruct mmg to use the GNU C++ compiler by setting the option -gnu 
or set option -a static to declare this module as unloadable. The reason 
of this problem may be a wrong handling of streams or templates. Refer 
to section 5.4 for details. 

A module cannot be loaded or initialized by MuPAD? Check if the 
module can be found by MuPAD. 

Check if the module was compiled for this hardware and software platform. 
Check if you have linked all libraries needed for your module. 

Try to re-generate the module using an alternative C++ compiler. Since 
different compilers may use different linking formats, your compiler may 
not be supported by MuPAD. 

Using streams, templates or C++ exceptions in a dynamic module, 
there are unresolved symbols or the MuPAD kernel reports a 
fatal error? Try to re-generate the module using an alternative C++ 
compiler and/or linker. Refer to section 5.2 for details. 

Avoid these features. Use the MAPI routines MFputs and MFprintf for 
displaying C/C++ objects. 

The compiler reports a warning . . .cannot inline function. . .? Most 
routines of MAPI are realized as C++ inline functions to gain optimal 
performance. Some compilers are not smart enough to handle arbitrary 
C/C++ statements in inline functions. Ignore the warning or look for an 
option to suppress it. 

The compiler reports a warning . . .statement is unreachable. . .? This 
compiler is not as smart as others. Ignore the warning or look for an option 
to suppress it. 




10. Demos and Applications 



This chapter contains module applications. They are distributed in the hope 
that they will be useful for your work, but without any warranty; without even 
the implied warranty of merchantability or fitness for a particular purpose. 
However, studying their sources may provide deeper insight in writing modules. 

The book only contains extracts of the module source code. The complete 
sources are available on the accompanying CD-ROM. See appendix A for con- 
tents information, installing instructions and license agreements. 



Table 10.1: Demonstration/ Application Navigator 



Section 


Description of module application 


(10.1) Examples 


Date function, Several source files, Calling filter programs. Pipe com- 
munication, Simple Internet access. Drawing fractals 


(10.1.7) gdb 


A module for automatic debugging on fatal errors (xxgdb) 


(10.2.1) stack 

(10.2.2) mfp 


A simple implementation of a user-defined data type 
A simple implementation of machine floating point arithmetic 


(10.3.1) imsl 

(10.3.2) nagc 


Using the numeric library IMSL within MuPAD 
Using the numeric library NAGC within MuPAD 


(10.4.1) gmp 


Using the GMP library for arbitrary precision arithmetic 


(10.5.1) magnum 

(10.5.2) ntl 

(10.5.3) gb/rs 

(10.5.4) sing 


Using the Magnum library for factoring polynomials 
Using the NTL library for arithmetic and factoring polynomials 
Computing Grobner basis and isolating real roots of polynomials 
Interfacing the Singular system for Grobner basis computation 


(10.6.1) asap 

(10.6.2) mp 

(10.6.3) net 


Integrating interprocess protocols: Using ASAP 
Using the MP communication protocol in MuPAD 
A prototype of the MuPAD macro parallelism 


(10.7.1) motif 

(10.7.2) pascal 

(10.7.3) pthread 

(10.7.4) scan 


Using XI 1/Motif widgets within dynamic modules 
Linking PASCAL routines into dynamic modules 
Using Posix threads within dynamic modules 
Creating MuPAD scanner modules using flex 
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10.1 Some Introducing Examples 

The modules described here are quite simple. They are intended to demonstrate 
the general concept of writing, creating and using dynamic modules in Mu PAD. 



10.1.1 A Date Function for MuPAD 

This example demonstrates a module date which provides a function new to 
determine the current date and time in form of a MuPAD character string. This 
example includes a module online documentation and can be used as follows: 



» module(date) : // load the dynamic module 

» date::doc(); // display the introduction 

MODULE 

date - A date function for MuPAD 
INTRODUCTION 

This module provides a date function to MuPAD. It is a simple example 
for writing module functions and using the module domain method ’new’. 
The implementation can be used on UNIX operating systems. 

[...] 

» date::new(); // get current date 

"Mon Mar 9 09:34:27 1998" 

» dateO; // it’s a shortcut 

"Mon Mar 9 09:34:45 1998" 



As simple as the functionality of this module is its source code. It consists of 
only a few lines of C/C++ code: 

1 /////////////////////////////////////////////////////////////////////////////// 

2 // MODULE: date.C — A date function for MuPAD 

3 // AUTHOR: Andreas Sorgatz (andi®uni-paderborn.de) 

4 // DATE : 03. Mar. 1998 

5 // TESTED: MuPAD 1.3, 1.4.0, Unix operating systems 

6 /////////////////////////////////////////////////////////////////////////////// 



7 


MFUNCC new, MCnop ) 


// 


Module function with Ho Options 


8 


{ time_t clock; 


// 


Declare your C++ variables 


9 


char *cstrg; 






10 








11 


MFnargsCheck(O) ; 


// 


Do not allow any arguments 


12 








13 


time(ftclock) ; 


// 


C++ code to get the current 


14 


cstrg = ctime(&clock) ; 


// 


date in form of a C string. 


15 


cstrg[24] = ’\0’; 


// 


Remove the ’\n’ at the end. 


16 








17 


MTcell mstrg = MFstring(cstrg) ; 


// 


Convert into a MuPAD string 


18 


MFreturn( mstrg ) ; 


// 


Return the result to MuPAD 


19 


} MFEND 







To create the module binary, the module generator mmg is called as follows: 
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andi> mmg -v date.C 

MMG — MuPAD-Module-Generator — V- 1.4.0 Feb. 98 
Mesg.: Scanning source file ... 

Mesg.: 1 function(s) and 0 option(s) found in 21 lines 
Mesg.: Creating extended module code ... 

Mesg. : Compiling extended module code . . . 

g++ -f no-gnu-1 inker -fpic -DSOLARIS -c ./MMGdate.C -o ./date.o 
-DPARI_C_PLUSPLUS -DL0NG_IS_32BIT -DP0INTER_IS_32BIT 
-I/user/andi/MUPAD/share/bin/ . ./. . /share/mmg/ include/kernel 
-I/user/andi/MUPAD/share/bin/ . ./. . /share/mmg/ include/acmatch 
-I/user/andi/MUPAD/share/bin/. ./. . /share/mmg/ include/pari 
Mesg. : Linking dynamic module . . . 
g++ -G -o ./date.mdm ./date.o 

-L/user/andi/MUPAD/share/bin/ . ./. ./solaris/lib 
Mesg. : Ok 



The plain text file date .mdh contains the online documentation for this module: 

MODULE 

date - A date function for HuPAD 
INTRODUCTION 

This module provides a date function to HuPAD. It is a simple example 
for writing module functions emd using the module domain method ’new’. 

The implementation can be used on UNIX operating systems. 

INTERFACE 
doc, new 
[...] 

<!— BEGIN-FUNC new — > 

NAME 

date: :new - Returns the current date and time 

SYNOPSIS 
date : :new() 

DESCRIPTION 

The function returns the current date and time as a character string. 

The end of line character, which typically ends this string on UNIX 
operating systems, is removed. Instead of ’date::new()’ the short-cut 
’dateO’ can be used to call this function. 

EXAMPLE : 

>> date : :new() ; 

"Mon Mar 9 09:34:27 1998" 

>> dateO ; 

"Hon Mar 9 09:34:45 1998" 

SEE ALSO 
rtime, time 
<!— END-FUNC — > 



Refer to the directory demo/DATE/ on the CD-ROM for additional information. 
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10.1.2 Splitting Modules into Several Source Files 

This example demonstrates how modules can be split into several source files 
(see section 5.2.3). For this, the source code of the module date described in 
the previous section is divided into two parts. 

The functionality to create a Mu PAD string with the current date and time is 
isolated by creating a file getdate.C containing a routine getdatestring: 

1 /////////////////////////////////////////////////////////////////////////////// 

2 // FILE : getdate.C — Implementation of a date function 

3 // AUTHOR: Andreas Sorgatz (andiQuni-paderborn.de) 

4 // DATE : 17. Mar. 1998 

5 // TESTED: MuPAD 1.3, 1.4.0, Unix operating systems 

6 /////////////////////////////////////////////////////////////////////////////// 



7 


MTcell getdatestringO 


// A C/C++ subroutine using MAPI 


8 


{ time.t clock; 




9 


time(Aclock) ; 


// C++ code to get the current 


10 


char* cstrg = ctime(Aclock) ; 


// date in form of a C string. 


11 


cstrg[24] = ’\0’; 


// Remove the ’\n’ at the end. 


12 


MTcell mstrg = MFstring(cstrg) ; 


// Convert into a MuPAD string 


13 


return ( mstrg ); 


// Return the result 


14 


} 





Because this code uses MAPI, mmg must be used to compile it (see section 5.2.3). 
Otherwise a C++ compiler could be used directly (also refer to section 8.3): 



andi> mmg -v -c main=date2 getdate.C 

MMG — MuPAD-Module-Generator — V- 1.4.0 Feb. 98 

Mesg. : Scanning source file . . . 

Mesg. : Creating extended module code ... 

Mesg.: Compiling extended module code ... 

g++ -f no-gnu-1 inker -fpic -DSOLARIS -c ./MMGgetdate.C -o ./getdate.o 
-DPARI_C_PLUSPLUS -DL0NG_IS_32BIT -DP0INTER_IS_32BIT 
-I/user/andi/MUPAD/share/bin/. ./. . /share/mmg/include/kernel 
-I/user/andi/MUPAD/share/bin/. ./. ./share/mmg/include/acmatch 
-I/user/andi/MUPAD/share/bin/. ./. . /share/mmg/include/pari 
Mesg. : Skipping linking of dynamic module 
Mesg. : Ok 



The module main source file date2 now only contains the following lines: 



1 

2 

3 

4 

5 

6 

7 

8 
9 

10 

11 



/////////////////////////////////////////////////////////////////////////////// 
// MODULE: date2.C — A date function for MuPAD 
// AUTHOR: Andreas Sorgatz (eindiQuni-paderborn .de) 

// DATE : 17. Mar. 1998 

// TESTED: MuPAD 1.3, 1.4.0, Unix operating systems 
/////////////////////////////////////////////////////////////////////////////// 
extern HTcell getdatestringO ; // External declaraction 

MFUHC( new, MCnop ) // Module function with lo OPtions 

{ MFnargsCheck(O) ; // Do not allow any arguments 

MFreturn( getdatestringO ); // Return the result to MuPAD 

} MFEHD 
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The module binary is then created by calling the module generator as follows: 



andi> mmg -v date2.C getdate.o 

MMG — MuPAD-Module-Generator — V- 1.4.0 Feb. 98 

Mesg.: Scanning source file ... 

Mesg.: 1 function(s) and 0 option(s) found in 14 lines 
Mesg.: Creating extended module code ... 

Mesg.: Compiling extended module code ... 

g++ -f no-gnu-linker -fpic -DSOLARIS -c ./MMGdate2.C -o ./date2.o 
-DPARI_C_PLUSPLUS -DL0NG_IS_32BIT -DP0INTER_IS_32BIT 
-I/user/andi/MUPAD/share/bin/. ./. . /share/mmg/ include/kernel 
-I/user/andi/MUPAD/share/bin/. ./. . /share/mmg/ include/acmatch 
-I/user/andi/MUPAD/shaire/bin/. ./. . /share/mmg/ include/pari 
Mesg.: Linking dynamic module ... 
g++ -G -o ./date2.mdm ./date2.o getdate.o 

-L/wiwianka/user/cube/MUPAD/share/bin/ . ./. ./solaris/lib 
Mesg. : Ok 



Refer to the directory demo/DATE2/ on the CD-ROM for more information. 



10.1.3 Executing UNIX Filter Programs 

This example demonstrates a module call which provides a function new to 
call a UNIX program returning its output as a Mu PAD character string. The 
function accepts an input character string. This is useful when executing filter 
programs as demonstrated below, new performs the simpliest way of interpro- 
cess communication and is useful to interact with special purpose tools. 



» module ( call ) : // load the module 

» print ( Unquoted, call("pwd") ); // current directory 

/user/andi/CDROM/demo/CALL 



» call( "be", "25+17\n" ); text2expr(*/,)-29; // call a math program 

"42" 

13 

» call( "sort", "bbb\naaa\nccc" ); // sort lines of words 

"aaa\nbbb\nccc" 



The output of call may be processed further by any Mu PAD function, e.g. by 
text2expr to convert it to a Mu PAD expression. The complete source code is: 
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1 /////////////////////////////////////////////////////////////////////////////// 

2 // NODULE: call.C — Simple interprocess process communication 

3 // AUTHOR: Andreas Sorgatz (andiQuni-paderborn.de) 

4 // DATE : 24. Mar. 1998 

5 // TESTED: HuPAD 1.3, 1.4.0, Unix operating systems 

6 /////////////////////////////////////////////////////////////////////////////// 

7 HTcell callit( char* prog, char* input=IULL ) 

8 { FILE *fd; 

9 char cmd [1024+1] = "\0"; 

10 char fil[64] = "\0"; 

11 

12 if( input ) { 

13 sprintfC fil, "/tmp/ . callit*/,ld" , getpidO ); 

14 if( (fd=fopen(fil,"H") ) == HULL ) MFerror( "Cannot write to /tmp" ); 

15 fprintfC fd, "7,s", input ); fcloseC fd ); 

16 sprintfC cmd, "cat */,s I ", fil ); 

17 } 

18 strcatC cmd, prog ); 

19 if( (fd=popen(cmd,"r")) == HULL ) { 

20 unlinkC fil ); HFerrorC "Cannot launch program" ); 

21 } 

22 HTcell string = HFstringC") ; 

23 char buf [1024+1] = "\0"; 

24 for( int bytes; (bytes=fread(buf ,1 ,1024,fd))>0; ) { 

25 bytes — ; buf [bytes] =* ’\0’; 

26 string = MFcalK "_concat", 2, string, MFstringCbuf ) ); 

27 } 

28 pcloseC fd ); unlinkC fil ); 

29 returnC string ); 

30 } 

31 /////////////////////////////////////////////////////////////////////////////// 

32 HFUHCC new, HCnop ) 

33 { HFnargsCheckRange (1,2); 

34 HFargCheckCl ,DOM_STRIHG) ; 

35 ifC MVnargs==2 ) { 

36 HFargCheck ( 2 , DOM^STRIHG) ; 

37 MFreturnC callitC HFstring(HFargCl) ) , HFstring(HFarg(2) ) ) ); 

38 } else 

39 MFreturnC callitC HFstring(HFargCl) ) ) ); 

40 } HFEHD 



Refer to the directory demo/CALL/ on the CD-ROM for more information. 



10.1.4 Calling UNIX Programs via Pipes 

This example demonstrates a module pipe which provides a set of functions to 
launch UNIX programs and to establish a text based communication via UNIX 
pipes with them. This is useful to interact with special purpose tools available 
as independent standalone programs. 

In contrast to the module call, described in the previous section, here, the 
UNIX program can be started once and an arbitrary number of send/receive 
transaction can be carried out then. 
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» module (pipe ) : 

» p:=pipe: :open("bc") ; 

[13939, 5, 6] 

» pipe: :put(p,"25+16\n") : 

» if( pipe: : timeout (p, 5) ) then "slave died" 
&> else pipe : :data(p) end_if; 

3 

» text2expr(pipe: :get(p) ) + 1; 

42 

» pipe: : close(p) : 



// load the module 
// call math program 

// send a job 
// wait for an answer 
// number characters? 

// get answer, use it 

// close the slave 



The output of pipe: :get may be processed further by any MuPAD function, 
e.g. text2expr to convert it into an expression. The complete source code is: 



1 /////////////////////////////////////////////////////////////////////////////// 

2 // MODULE: pipe — A simple implementation of a HuPAD-slave communication 

3 // AUTHOR: Andreas Sorgatz (andi@uni-paderborn.de) 

4 // DATE : 20. Apr. 1998 

5 /////////////////////////////////////////////////////////////////////////////// 

6 #if defined SOLARIS 

7 # include <sys/f ilio . h> 

8 #endif 

9 #include <sys/wait.h> 

10 #include <sys/ioctl .h> 

11 #include <fcntl.h> 

12 #define PIPE.READ 0 

13 #define PIPE.WRITE 1 

14 #define PIPE.BUFLEN 5001 

15 

16 // Initializes file descriptors /////////////////////////////////////////////// 

17 static int my_set_fl( int fd, int flags ) 

18 { int val; 

19 if( (val=fcntl(fd , F_GETFL, 0 )) < 0 ) return( -1 ); val |= flags; 

20 if( (val=fcntl(fd, F.SETFL, val)) < 0 ) return( -1 ); return( 0 ); 

21 } 

22 // Check and and read-out HuPAD pipe handles ////////////////////////////////// 

23 static void get_des ( HTcell des , long *s_pid, int *s_in, int *s_out ) 

24 { HTcell val; 

25 if( IMFisList (des) || MFnops(des) != 3 ) HFerror( "Bad pipe descriptor"); 

26 if( !HFisInt(val=HFgetList(&des ,0) ) ) MFerror("Bad pipe descriptor"); 

27 *s_pid = HFlong( val ) ; // process-id of slave process 

28 if( !MFisInt(val=HFgetList(&des ,1) ) ) HFerrorC'Bad pipe descriptor"); 

29 *s_in = (int) MFlong( val ); // handle of the slave’s stdin 

30 if( IHFisInt (val=HFgetList(&des ,2) ) ) HFerror( "Bad pipe descriptor"); 

31 *s_out = (int) HFlong( val ); // handle of the slave’s stdout 

32 } 

33 /////////////////////////////////////////////////////////////////////////////// 

34 // FUICTION: close( sdesc : DOM.LIST ) : D0H_HULL 

35 // Terminates the slave and closes the pipe. Subprocesses of the slave cannot 

36 // be terminated by MuPAD! 

37 /////////////////////////////////////////////////////////////////////////////// 

38 MFUNC( close, HCnop ) 

39 { long s_pid; 

40 int s_in, s_out, status; 

41 MFnargsCheck( 1 ); get_des( MFarg(l) , &s_pid, &s_in, &s_out ); 

42 kill ( s_pid, SIGTERH ); sleep(l); wait( ftstatus ); 

43 close( s_in ); close( s_out ); 

44 MFreturn( MFcopy (HVnull) ) 

45 } HFEHD 
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46 

47 

48 
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/////////////////////////////////////////////////////////////////////////////// 
// FUICTIOH: data ( sdesc : DOH.LIST ) : DOH.IIT 
// Returns the number of characters, send by the slave ’sdesc’. 
/////////////////////////////////////////////////////////////////////////////// 
MFUHC( data, MCnop ) 

{ long s_pid; 

int s_in, s_out, bytes; 

HFnargsCheckC 1 ); 

get_des( MFarg(l), fts.pid, fts_in, fts_out ); 

#if defined linux 

if( ioctl(s_out , FI OHREAD, kbytes ) !=0 ) HFerrorC "Can’t determine pipe status"); 
HFreturnC MFlong(bytes) ) 

#else 

struct stat sbuf; 

if( fstat (s_out ,&sbuf ) !=0 ) HFerror ("Can ’ t determine pipe status"); 

HFreturnC HFlong(dong) sbuf .st_size) ) 

#endif 
} HFEHD 

/////////////////////////////////////////////////////////////////////////////// 
// FUNCTION: get( slave : DOH.LIST [, num : DOH.INT] ) : DOH.STRING 
// Read all (or ’num’) characters from the ’slave’ output stream. This is a 
// non-blocking read, which may return the empty string "". 
/////////////////////////////////////////////////////////////////////////////// 
MFUNCC get, MCnop ) 

{ char buf[PIPE_BUFLEN] = "\0"; 
long s_pid, get, num; 
int s^out, s_in; 

HFnargsCheckRangeC 1,2); 
if( HVnargs == 2 ) { 

HFargCheckC 2, DOH.INT ); 

if( (get=HFlong(HFarg(2)) )<0L ) HFreturnC MFcopy(HVfail) ); 

} else get = PIPE.BUFLEN-l ; 

HFargCheckC 1, DOM.LIST ); 

get_des( HFarg(l), fts.pid, fts_in, &s_out ); 

num = readC s_out, buf, (int)get ); 

ifC num == -1 ) HFerrorC "Can’t read from pipe" ); 

if ( num > 0 ) buf [num] = ’ \0 ’ ; 

HFreturnC HFstringCbuf) ) ; 

} MFEND 

/////////////////////////////////////////////////////////////////////////////// 
// FUNCTION: put( sdesc : DOH.LIST, string : DOH_STRING ) : D0H_INT 
// Sends ’string’ to the slave ’sdesc’. The functions returns the number of 
// succesfully sent characters. 

/////////////////////////////////////////////////////////////////////////////// 

HFUNCC put, MCnop ) 

{ long s_pid, num; 
int s_in, s_out; 

HFnargsCheckC 2 ) ; 

HFargCheckC 1, D0H_LIST ); 

get_des( HFargCl), fts.pid, fts_in, &s_out ); 

HFargCheckC 2, DOH^STRING ); 

char *strg = HFstringC HFarg(2) ) ; 

num = writeC s_in, strg, strlenCstrg) ); 

if( num == -1 ) HFerrorC "Can’t write to pipe" ); 

HFreturnC HFlongCnum) ) 

} HFEND 

/////////////////////////////////////////////////////////////////////////////// 

// FUNCTION: openC slave : DOM.STRING ) : D0M_LIST 

// ’slave’ is a UNIX shell command/program. It is lauched emd its stdin, stdout 
// and stderr stream is redirected. The functions returns a pipe descriptor of 
// the form: [ process-id, slave- input-stream, slave-output-stream ] 

/////////////////////////////////////////////////////////////////////////////// 

HFUNCC open, MCnop ) 

{ char *strg, buf [512] ; 

int s_pid, s_in[2] , s_out[2]; 

MTcell list; 
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HFnargsCheckC 1 ); HFargCheck( 1, DOH.STRIHG ); strg = HFstringC MFarg(l) ); 
if( pipe( s_in ) != 0 ) HFerror( "Can’t open pipe" ); 
if( pipe( s_out) != 0 ) { 

close ( s.inCPIPE.READ ] ); 
close( s_in[PIPE_WRITE] ); 

MFerrorC "Can’t open pipe" ); 



} 

if( (s_pid = forkO) == 0 ) { 
close( s_in [PIPE.WRITE] ); 
close ( s_out[PIPE_READ ] ); 
close ( 0 ) ; 

if( dup2(s_in [PIPE.READ ] ,0) == -1 ) _exit( 1 ) 
close( s_in [PIPE.READ ] ); 
closeC 1 ) ; 

if( dup2 (s_out [PIPE.WRITE] ,1) == -1 ) _exit( 1 ); 
close( 2 ) ; 

if( dup2(s_out [PIPE.WRITE] ,2) == -1 ) .exit( 1 ); 
close ( s. out [PIPE.WRITE] ); 
sprintfC buf, "exec %s" , strg ); 
execlC "/bin/sh", "/bin/sh", "-ec", buf, NULL ); 
.exit ( 1 ) ; 



// executed by slave 



// slave’s stdin 

// slave’s stdout 
// slave’s stderr 

// launch program 



// Initialize the MuPAD kernel for pipe communication /////////////////////// 
if( s.pid ==-!){ 

close( s.in [PIPE.READ] ); close( s.in [PIPE.WRITE] ); 
closeC s. out [PIPE.READ] ); close( s. out [PIPE.WRITE] ); 

MFerrorC "Can’t fork process" ) ; 

} 

closeC s.in [PIPE.READ] ); 
closeC s.out [PIPE.WRITE] ); 

ifC my.set.fl Cs.out [PIPE.READ] .O.NOIBLOCK) < 0 ) { ; } // ignore 

// Create and return pipe descriptor //////////////////////////////////////// 



list = HFnewListC 3 ); 

HFsetListC ftlist, 0, HFlongCs.pid) ); 

HFsetListC ftlist, 1, HFlongCs.in [PIPE.WRITE]) ); 
HFsetListC ftlist, 2, HFlongCs.out [PIPE.READ ] ) ); 
HFsigC list ) ; 

HFreturnC list ) ; 



} MFEHD 

/////////////////////////////////////////////////////////////////////////////// 

// FUNCTION: timeout C sdesc : DOM.LIST, sec : DOH.INT ) : DOH.INT 

// The function waits up to ’sec’ seconds for an answer of the slave ’sdesc’. 

// If there are any data, then the function returns FALSE else TRUE. 
/////////////////////////////////////////////////////////////////////////////// 
HFUNCC timeout, HCnop ) 

{ long s.pid, sec; 

int s.in, s.out, bytes, data; 

unsigned long tl, t2; 



HFnargsCheckC 2 ) ; 

MFargCheckC 1, DOM.LIST ); get.desC HFargCl) , fts.pid, fts.in, fts.out ); 
HFargCheckC 2, DOH.INT ); sec = HFlongC HFargC2) ); 

ifC sec < OL I I sec > 3600L ) MFerrorC "Seconds must be in [0..3600]" ); 



forC data = 0, tl = t2 = time C NULL ) ; Ct2-tl) < sec; t2 = timeCNULL) ) { 

#if defined linux 

if CioctlCs.out ,FI0NREAD ,ftbytes) !=0) HFerror C'Can ’t determine pipe status"); 
ifC Cdata = bytes) ) break; 

#else 

struct stat sbuf ; 

if CfstatCs.out ,ftsbuf ) !=0) MFerrorC "Cam ’t determine pipe status"); 
ifC Cdata = sbuf . st. size) ) breaik; 

#endif 

} 

HFreturnC MFboolCdata<=0) ); 

} HFEND 
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The next example demonstrates the simple library package maple. mu which is 
based on the dynamic module pipe and enables Mu PAD users to launch the 
computer algebra system Maple^ -if this is installed on their local machine- and 
to intercat with it within a Mu PAD session: 
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This module may also be used to interact with mathematical internet databases, 
e.g. like Tilu [10] as proposed by Richard Fateman. Also refer to [53]. 

The output of fetch may be processed further by use of the string library 
package or any other Mu PAD function. The complete module source code con- 
sists of only about 60 lines of C/C++ code: 

1 /////////////////////////////////////////////////////////////////////////////// 

2 // MODULE: fetch.C -- A simple Internet access function for HuPAD 

3 // AUTHOR: Andreas Sorgatz (andi@uni-paderborn.de) 

4 // DATE : 24. Mar. 1998 

5 /////////////////////////////////////////////////////////////////////////////// 

6 MMG( Solaris: loption = ''-Insl -Isocket" ) 

7 

8 #include <sys/socket . h> 

9 #include <netdb.h> 

10 #include <netinet/in . h> 

11 #if defined SYSV 

12 # define bcopy(x,y,n) memcpy (y ,x ,n) 

13 # define bzero(x,y) memset(x,0,y) 

14 #endif 

15 

16 /////////////////////////////////////////////////////////////////////////////// 

17 MTcell fetchitC char* host, u.short port, char* query ) 

18 { // Get hostentry and initialize it ////////////////////////////////////////// 

19 struct hostent *hen; 

20 struct sockaddr.in sai ; 

21 if( ! (hen=gethostbyname(host)) ) MFerror( "Unknown host" ); 

22 bzero( (char*)ftsai, sizeof(sai) ); 

23 bcopyC hen->h_addr, (char *) &sai . sin_addr , hen->h_length ); 

24 sai . sin.family = hen->h_addrtype ; 

25 sai.sin.port = htons( (u.short) port ); 

26 

27 // Open socket and connect to remote system ///////////////////////////////// 

28 int socketfd; 

29 if( (socketfd=socket (hen->h_addrtype , SOCK_STREAM, 0)) <0 ) 

30 MFerror( "Cein’t open local socket" ); 

31 if( connect (socketfd, (struct sockaddr *) ftsai, sizeof(sai)) < 0 ) { 

32 close( socketfd ); MFerror( "Ccin’t connect to host/port" ); } 

33 

34 // Send query string //////////////////////////////////////////////////////// 

35 if( *query && (write(socketfd, query, strlen(query) ) < 1) ) { 

36 close( socketfd ); MFerror( "Can’t send query" ); } 

37 

38 // Read until error or end of file ////////////////////////////////////////// 

39 MTcell string = MFstringC") ; 

40 char buffer [1024+1] = "\0" ; 

41 for( int bytes; (bytes=read(socketfd, buffer ,1024) )>0; ) { 

42 buffer [bytes] = ’\0’; 

43 string = MFcalK "_concat", 2, string, MFstring(buffer) ); 

44 } 

45 close( socketfd ) ; 

46 return( string ) ; 

47 } 

48 /////////////////////////////////////////////////////////////////////////////// 

49 MFUIC( new, MCnop ) 

50 { MFnargsCheck( 3 ) ; 

51 MFargCheck(l,DOM_STRIHG) ; MFargCheck(2 ,D0M_IHT) ; MFargCheck(3 ,D0M_STRI1IG) ; 

52 MFreturn( fetchit( 

53 MFstring(MFargd) ) , (u_short) MFlong(MF2u:g(2) ) , MFstring(MFarg(3) ) 

54 ) ); 

55 } MFEHD 



Refer to the directory demo/FETCH/ on the CD-ROM for more information. 
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10.1.6 Plotting Dragon Curves 

The module dragon is just a game to play. It allows to create large dragon 
curves in the form of polygons, which can be displayed by the Mu PAD graphics 
tool vcam. A dragon curve is defined as follows: 

Let n be a positive integer. A dragon curve Dn is a sequence of elements 0 , 1 
with: Do := 1 and Dn := Dn-ilDn-i^^ Ergo Di = 110, D 2 = 1101100 and so 
on. Exponential time and memory is needed to create a dragon curve. 

To display a dragon, with a pen and with constant speed draw a straight line 
on a piece of paper, while interpreting the dragon sequence. Reading the value 
1 , turn right (—90 degree) and reading the value 0, turn left (90 degree). You 
will get a nice fractal image. 

The dynamic module dragon can be used as demonstrated below: 



» module (dragon) : 

» dragon (0) ; 

polygon(point(0, 0, 0), point(0, 0, 1), point(l, 0, 1)) 



» plot3d( 
» plot3d( 
» plot3d( 
» plot3d( 



[Mode=List , 
[Mode=List , 
[Mode=List , 
[Mode=List , 



Cdragon(2)]] ): 
[dragon(4)]] ): 
[dragon(6)]] ): 
[dragon (12)]] ): 



The example above produces fractal images similar to the following ones: 




Figure 10.1: The Dragon Curves D 2 , D 4 , Dq and Du 

The source code of the dragon module gives an example for using the MAPI 
routine MFcmalloc. This module uses undocumented Mu PAD kernel features. 
Also refer to appendix B.3. 



1 //////////////////////////////////////////////////////////////////////////// 

2 // FILE : dragon. C - Dragon Curves 

3 // AUTHOR: Andreas Sorgatz (andiQuni-paderborn .de) 

4 // DATE : 21. Feb. 1997 

5 // TESTED: MuPAD 1.4.0, Linx 2.0, Solaris 2.5 

6 //////////////////////////////////////////////////////////////////////////// 

7 enum { NORTH, EAST, SOUTH, WEST }; // Directions to move the writing pen 
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8 //////////////////////////////////////////////////////////////////////////// 



9 


MFUIC( new, HCnop ) 


// Declare the function ’new 


10 


{ MFnargsCheck(l) ; 


// One arguments is expected 


11 


MFargCheck(l,DOM_IIT); 


// this must be an integer 


12 


HTcell argl = MFarg(l); 


// The first parameter 


13 


HTcell Int31 = MFlong(31); 


// Create D0H.IIT(31) 


14 


if( MFlt(argl,MVzero) || MFgt(argl ,Int31) ) 


15 


HFerror( "Integer out of range [0. 


.31]" ); 


16 


HFfree(Int31) ; 


// It is not longer needed 


17 


long iter = HFlong(argl) ; 


// Convert into a C long 


18 


long size = (2L « iter)~lL; 


// Size of dragon 


19 


char* dragon = (char*)HFcmalloc(size) ; 


// Create a byte vector 


20 


dragon [0] = 1 ; 


// Create the dragon 


21 


for( long len = 1; iter — ; len = 2*len+l ) { 


22 


dragon [len] = 1; 




23 


for( long i = 1; i <= len; i++ ) dragon [len+i] = ( dragon [len-i] ? 0:1 


24 


} 




25 


long posx = 0, posy = 0; 




26 


HTcell tmpl , tmp2 ; 




27 


HTcell pol = HFnewPolygon(size+2) ; 


// Create an empty polygon 


28 


HTcell* pnt = HFopAdr(pol ,0) ; 


// Reference to 1th point 


29 


*pnt++ = HFnewPoint(tmpl=HFlong(posx) , 


HVzero, tmp2=HFlong( posy)); 


30 


HFfree(tmpl) ; HFfree(tmp2) ; 




31 


*pnt++ = HFnewPoint (tmpl=HFlong(posx) , 


HVzero, tmp2=HFlong(++posy) ) ; 


32 


HFfree(tmpl) ; HFfree(tmp2) ; 




33 


for( int i=0, go=N0RTH; i < size; i++ 1 


{ // Check where to go next 


34 


switch( go ) { 




35 


case NORTH: if( dragon [i] ) posx++ 


else posx — ; break; 


36 


case EAST : if( dragon [i] ) posy — 


else posy++; break; 


37 


case SOUTH: if( dragon [i] ) posx — 


else posx++; break; 


38 


case WEST : if( dragon [i] ) posy++ 


else posy — ; bre^dc; 


39 


default : HFerror( "Fatal error" 


); 


40 


} 




41 


go = (go + (dragon [i] ? 1:3)) */, 4; 




42 


*pnt++ = HFnewPoint (tmpl=HFlong(posx 


), HVzero, tmp2=HFlong(posy) ) ; 


43 


HFf ree(tmpl) ; HFfree(tmp2) ; 




44 


} 




45 


HFcfree( dragon ); 


// Free the byte vector 


46 


HFsig(pol) ; 


// Create a new signature 


47 


HFreturn(pol) ; 


// Return the polygon 


48 


} HFEHD 





Refer to the directory demo/DRAGON/ on the CD-ROM for more information. 

10.1.7 Automatic Debugging of Modules 

Writing C/C-|--f- programs as well as dynamic modules, it is often necessary to 
use a source level debugger to find and correct errors. Section 8.7 gives general 
information about debugging dynamic modules in Mu PAD. 

This section describes the module gdb which provides an interface to the GNU 
debugger xxdbg. If the kernel or a module function produces a fatal error, the 
debugger is called instead of quitting the kernel. This enables kernel as well as 
module programmers to get detailed information about the current problem. 

To debug a module, change into the directory in which the source code as well 
as the module binary is located. Start Mu PAD and load the debugger module. 
Then execute the command which crashes the kernel. The following message 
will be displayed when the fatal error occurs 
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» module (gdb) : 

Debugger interface is active. Debugger: ^xxgdb*, Process: 14938 
» module (demo ) : 

» demo : : buggyf unc ( ) ; 

######################################################### 

# PRESS ANY KEY TO CONTINUE AFTER QUITING THE DEBUGGER! # 

# OR PRESS Ctrl-Z TO SUSPEND THE CURRENT MuPAD PROCESS. # 
######################################################### 



and the debugger is started automatically. It can be used as usual. After quit- 
ting it, change to the MuPAD session window and either press the RETURN 
key to try to continue the current MuPAD session or press CTRL-Z to sus- 
pend and then kill the MuPAD kernel. The MuPAD session window displays the 
following message when the session is going on: 



» module (gdb): 

Debugger interface is active. Debugger: *xxgdb\ Process: 14938 
» module (demo ) : 

» demo : : buggyf unc ( ) ; 

######################################################### 

# PRESS ANY KEY TO CONTINUE AFTER QUITING THE DEBUGGER! # 

# OR PRESS Ctrl-Z TO SUSPEND THE CURRENT MuPAD PROCESS. # 
######################################################### 
######################################################### 

# YOUR BACK TO THE MuPAD SESSION. # 

######################################################### 



Note: After the kernel or a module function ran into a fatal error, it may not 
be possible to continue the current MuPAD session. 

Note: Unfortunately, on some systems, the debugger may not display the source 
file as well as the debug information instantly. If this happens, carry out the 
following actions to get it run: 

1. Execute the debugger command CO NT (continue) and 

2. change to the MuPAD session window. Type RETURN. 

3. Go back to the debugger and start debugging. 



Note: Using xmupad the message YOUR BACK TO THE MuPAD SESSION 
may not be displayed. Just press the INTERRUPT button of the MuPAD 
session window to first interrupt and then continue the current session. 
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The module also enables the user to exchange the debugger (gdb: :path), to 
inactivate it (gdb: : active), to call it implicitly (gdb: :new) and more. 

The complete source code of the module gdb is listed below. An important 
aspect of this module is the fact that it contains an interrupt handler. Thus 
it must be declared as a static module (refer to section 4. 7. 1.2). Furthermore, 
because the module interferes deep into the Mu PAD kernel, it uses some undoc- 
umented kernel features. The routine setIntrHandler describes which UNIX 
signals are caught by the module dbg. 

1 /////////////////////////////////////////////////////////////////////////////// 

2 // MODULE: gdb — HuPAD Module for interactive debugging 

3 // AUTHOR: Andreas Sorgatz (andiQmupad.de) 

4 // DATE : 27. Mar. 1998 

5 /////////////////////////////////////////////////////////////////////////////// 

6 MMG( attribute = "static" ) // because the module contains an interrupt handler 

7 

8 static char procid[32] = "\0" ; 

9 static char mupnam[256] = "mupad" ; 

10 static char debnam[256] = "xxgdb" ; 

11 static char* args[4] = { debnam, mupnam, procid, lULL }; 

12 static volatile long calldeb = 1; 

13 static volatile long loop = 0; 

14 



15 

16 
17 


void MUP_catch_system_ 


errorC VOID 


) ; // undocumented kernel routine 


/////////////////////////////////////////////////////////////////////////////// 


18 


void setIntrHandler ( void* handler ) 


19 


{ MUP.setsigC SIGILL , 


hemdler ) ; 


MUP.setsigC SIGFPE , handler ) ; 


20 


MUP_setsig( SIGBUS , 


handler ) ; 


MUP.setsigC SIGSEGV, handler ); 


21 


MUP.setsigC SIGPIPE, 


handler ) ; 


MUP.setsigC SIGPIPE, handler ); 


22 


#ifdef SOLARIS 






23 


MUP.setsigC SIGSYS , 


handler ) ; 




24 


#endif 






25 

26 


} 






27 


/////////////////////////////////////////////////////////////////////////////// 


28 


void dbgCallC void ) 






29 


{ int pid; 




// to store process id 


30 


MFputsC "\nStarting debugger. . . 


' ); 


31 


ifC (pid=forkO) == 


0 ) { 


// father process 


32 


osStoprawO ; 




// resets the terminal 


33 


execvp(args[0] , 


args) ; 


// overlays with debugger 


34 


MFputsC "Cem’t start the debugger." ); // exec failed 


35 


MUP. catch. system.errorO ; 




36 


} else ifC pid == -1 


) { 


// fork failed 



37 MFputs( "Can’t fork the MuPAD kernel process." ); 

38 MUP_catch_system_error() ; 

39 } else { 

40 

41 

42 

43 

44 

45 

46 

47 

48 

49 

50 

51 } 

52 } 

53 



MFput s ( "#####«###################»################«######»#######" ) 
MFputsC"# PRESS AIY KEY TO COITIIUE AFTER QUITIIG THE DEBUGGER! #") 
MFputsC# OR PRESS Ctrl-Z TO SUSPEID THE CURREIT MuPAD PROCESS. #") 
MFput s ( "####«#############################«######################" ) 

if( loop==l ) { while(l){}; } 

else { osGetchO; // child waits for any key 

osStartrawO ; // and resets the terminal 

} 

MFput s ( "#####«»############»«#ff #«########»#####»###«#############" ) 

MFputsC# YOUR BACK TO THE MuPAD SESSION . #") 
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54 /////////////////////////////////////////////////////////////////////////////// 

55 void dbgIntrHandler( void ) 

56 { setIntrH 2 mdler( dbgIntrHandler ); // install intr. handler 

57 if( icalldeb ) MUP_catch_system_error() ; 

58 dbgCallO; 

59 } 

60 

61 /////////////////////////////////////////////////////////////////////////////// 

62 HFUHC( initmod, HCnop ) 

63 { setIntrHandler( dbgIntrHandler ); // install interrupt handler 

64 sprintf( procid, "’/.Id" , getpidO ); // insert process-id 

65 sprintf( mupnam, "*/,s" , HUT_PROG_IAME ); // fullname of mupad binary 

66 HFprintfC "Debugger interface is active. Debugger: ’7,s’, Process: 7,ld\n" , 

67 debnam, getpidO ); 

68 HFreturnC MFcopy(HVnull) ); 

69 } HFEHD 

70 

71 /////////////////////////////////////////////////////////////////////////////// 

72 MFUNC( new, HCnop ) 

73 { HFnargsCheck(O) ; dbgCallO; 

74 HFreturn( HFcopy(HVnull) ) ; 

75 } HFEHD 

76 

77 /////////////////////////////////////////////////////////////////////////////// 

78 HFUHC( path, HCnop ) 

79 { HFnargsCheckRange( 0, 1 ); 

80 HTcell nam = HFstring( debnam ) ; 

81 if( HVnargs==l ) { 

82 HFargCheck( 1, DOH.STRIHG ); 

83 strcpy( debnam, HFstring(HFargd) ) ); 

84 } 

85 HFreturn( nam ) ; 

86 } HFEHD 

87 

88 /////////////////////////////////////////////////////////////////////////////// 

89 HFUHC( pid, HCnop ) 

90 { HFnargsCheck(O) ; 

91 HFreturnC HFlong(getpidO) ); 

92 } HFEHD 

93 

94 /////////////////////////////////////////////////////////////////////////////// 

95 HFUHC( active, HCnop ) 

96 { HFnargsCheckRange(0,l) ; 

97 HTcell val = HFbooK calldeb ); 

98 if( HVnargs==l ) { 

99 HFargCheckCl ,D0H_B00L) ; 

100 if ( HFisUnknown(HFargd) ) ) HFerrorC "Invalid argument" ); 

101 calldeb = HFbooK HFarg(l) ); 

102 } 

103 HFreturnC val ); 

104 } HFEHD 

105 

106 /////////////////////////////////////////////////////////////////////////////// 

107 HFUHCC noreturn, HCnop ) 

108 { HFnargsCheckRangeC 0, 1 ); 

109 HTcell val = HFbooK loop ); 

110 ifC HVnargs==l ) { 

111 HFargCheckC 1, DOH.BOOL ); 

112 if ( HFisUnknown(HFargd)) ) HFerrorC "Invalid argument" ); 

113 loop = MFboolC HFargCl) ); 

114 } 

115 HFreturnC val ) ; 

116 } HFEHD 



Refer to the directory demo/GDB/ on the CD-ROM for additional information. 
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10.2 User-defined Data Types 

This section demonstrates how user-defined data types can be implemented via 
dynamic modules by use of so-called MuPAD domains (see section 6.7.10). Refer 
to section 7.4 for additional information. 



10,2.1 Implementation of a Stack 

The module stack shows the implementation of the abstract data type stack. 
It provides a function new to create a stack, push to put an element on top of 
the stack and pop for taking the top element from the stack. It can be used as 
follows. Note the reference effect between s and ss. 



» module ( stack) : 

» s :=stack() ; 

» stack: :push(s ,a) : 
» ss:=s; 

» stack: :pop(s) , ss 
» stack: :pop(ss) , s 
» stack: :pop(s) ; 



// load the module 
// create a new stack 
Stack([]) // the empty stack 

stack: :push(s ,b) : stack: :push(s , c) : 

// create a reference 

Stack ([a, b, c] ) 

// reference effect 

c, Stack ([a, b] ) 

// reference effect 

b, Stack ([a]) 



a 

» stack: :pop(s) ; 

Error: Stack is empty [stack: :pop] 

» s. First: s. Second; // shortcut (_concat) 

StackC [First , Second]) 



The source code below contains two special features. The first is the function 
print which is responsible for formatting a stack before it is displayed. It is 
called automatically by the MuPAD kernel if it is needed and defined by the 
user. The second feature is the module procedure (see section 5.1.3) _concat 
which allows to use the concatenation operator ’ . ’ to push an element on the 
stack. This concept is called function overloading for user-defined data types 
and is described in section 2.3.19.2 of the MuPAD User’s Manual [50]. Refer to 
section 3.3 for additional information about overload able domain methods. 

1 /////////////////////////////////////////////////////////////////////////////// 

2 // MODULE: stack — A trivial implementation of a stack 

3 // AUTHOR: Andreas Sorgatz (andi@mupad.de) 

4 // DATE : 18. Mar. 1998 

5 /////////////////////////////////////////////////////////////////////////////// 

6 #define CHECK(n) if ( !MFisExt(HFarg(n) ,MVdomain) ) HFerror ("Invalid argument") 
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8 iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiimiiiiiiin 

9 MPR0C( _concat = "hold(stack: :push)" ); //a shortcut 

10 

11 /////////////////////////////////////////////////////////////////////////////// 



12 


HFUNCC new, HCnop ) 


// create a new stack 


13 


{ HFnargsCheck( 0 ) ; 




14 


MTcell stack = HFnewExtC HFcopy(MVdomain) , 1 ); 


// as a domain element 


15 


HFsetExt ( ftstack, 1, HFnewList(O) ); 


// with an empty list 


16 


MFsigC stack ) ; 


// compute signature! 


17 


HFreturn( stack ) ; 





18 } NFEID 

19 

20 /////////////////////////////////////////////////////////////////////////////// 

21 HFUICC print, HCnop ) // display a stack 

22 { HFnargsCheck( 1 ); CHECK(l); 

23 MTcell stack = MFarg( 1 ) ; // get stack parameter 

24 MTcell cont = NFgetExt( kstack, 1 ); // cont of the stack 

25 HFreturn( MFneuExpr(2 ,HFident ("Stack") ,HFcopy(cont)) ); 

26 } HFEID 

27 

28 /////////////////////////////////////////////////////////////////////////////// 



29 


HFUICC push, HCnop ) 


// push element on top 


30 


{ HFnargsCheck( 2 ); CHECK(l); 




31 


MTcell stack = HFargC 1 ) ; 


// get stack parameter 


32 


MTcell cont = HFgetExtC ftstack, 1 ); 


// content of the stack 


33 


MTcell elem = HFcopyC HFarg(2) ); 


// get element parameter 


34 


HFnopsListC ftcont, HFnops(cont)+l ); 


// increment size of list 


35 


HFsetListC ftcont, HFnops(cont)-l , elem ); 


// insert new element 


36 


MFsigC cont ) ; 


// compute signature! 


37 


MFsetExtC ftstack, 1, cont ); 


// insert new address 


38 


MFsigC stack ) ; 


// compute signature! 


39 


MFreturnC MFcopy(stack) ) ; 


// return a logical copy 


40 

A 4 


} MFEID 




42 


/////////////////////////////////////////////////////////////////////////////// 


43 


HFUICC pop, HCnop ) 


// pop element from top 


44 


{ HFnargsCheckC 1 ); CHECK(l); 




45 


MTcell stack = HFargC 1 ) ; 


// get stack parameter 


46 


MTcell cont = HFgetExtC ftstack, 1 ); 


// content of the stack 


47 


long num = HFnops(cont) ; 


// length of content 


48 


ifC num == 0 ) MFerrorC "Stack is empty" ); 




49 


MTcell elem = HFcopyC HFgetListCftcont ,num-l) ) 


; // get copyC!) of top e. 


50 


HFnopsListC ftcont, num-1 ); 


// decrement size of list 


51 


MFsigC cont ) ; 


// compute signature! 


52 


MFsetExtC ftstack, 1, cont ); 


// insert new address 


53 


MFsigC stack ) ; 


// compute signature! 


54 


MFreturnC elem ) ; 


// return top element 


55 


} HFEID 





The method _concat is defined as a module procedure (see line 10 of the source 
code). Thus, when the module generator is called to create the binary, it also 
creates the file stack. mdg (see section 7.2) which contains the following data: 

#^it************’i‘************************************************it 

9 * FILE Inline procedures/expressions of a dynamic module ♦# 

#* CREATED: on 18. Mar. 98, by module generator mmg Rel-1.4.0 

ff^t^Hl^^l^Cil^titl^Tlt^l^ltit************************************************ 

table ( "include" = [ 

"_concat" = holdCstack : :push) , 
nullO 
] ): 



Refer to the directory demo/STACK/ on the CD-ROM for additional information. 
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10.2.2 Using Machine Floating Point Numbers 

A second example of a user-defined data structure in Mu PAD is the module mf p 
which defines the domain of machine fioating point numbers. It can be used to 
speed up numerical computations in MuPAD.^ 

Note, that the representation of machine fioating point numbers (double) is 
usually limited to 12-14 valid digits on 32bit architectures. Thus, have a careful 
look at rounding errors etc. The module can be used as follows: 



» module (mfp): 

» fa:=mfp(l .4) : fb:=mfp(2 . 0) : 

» f c :=fa+fb*sin(fb) ; 

3.218594853 

» ma:=1.4: mb: =2.0: 

» ma+mb*sin(mb) -expr(fc); 

0 . 000000000000004057518207 



// load the module 
// two mfp numbers 
// the usual syntax 

// use 12 digits 
// compare to PARI 



» time((for i from 
time ((for i from 



1 to 1000 do sin(ma) end_for)), 
1 to 1000 do sin(fa) end.for)); 
2480, 1130 



// its faster 
// mfp is faster 



» mysin:=mfp: : sin: 

» time((for i from 1 to 1000 do sin(ma) end_for)), 
time((for i from 1 to 1000 do mysin(fa) end^for)); 
2500, 300 



// use directly 

// its fastest 
// call it directlj 



One can see, that the Sin function for mfp numbers is much faster, but most of 
its efficiency gets lost by the Mu PAD overload mechanism. The consequence is: 
to gain significant speedup, avoid to let Mu PAD look for an overloaded method 
but call the corresponding function directly. 

Because the 1.4 kernel currently does not provide an internal data structure to 
integrate user C/C-f + data into Mu PAD in a proper way, in this example a dirty 
trick is used: the machine fioating point number is stored in the memory block 
(read section 4.4) of a domain element. The number must be placed behind the 
information which is already stored in the memory block. Furthermore, one has 
to note that on some operating systems a sizeof (double) alignment must be 
used for objects of type double. 

1 /////////////////////////////////////////////////////////////////////////////// 

2 // MODULE: mfp — HuPAD Module for using machine floating point numbers 

3 // AUTHOR: Andreas Sorgatz (andi@mupad.de) 

4 // DATE : 17. Apr. 1997 

5 /////////////////////////////////////////////////////////////////////////////// 

6 



^The Mu PAD kernel 1.4 uses arbitrary precision floating point numbers otherwise. 
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8 
9 

10 

11 

12 
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15 

16 

17 

18 

19 

20 
21 
22 

23 

24 
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27 

28 

29 

30 

31 

32 

33 

34 

35 

36 

37 

38 

39 

40 

41 

42 

43 

44 

45 

46 

47 

48 

49 

50 

51 

52 

53 

54 



/////////////////////////////////////////////////////////////////////////////// 
static NTcell newNFPC HTcell domain, double cval ) // uses undocumented feature 
{ HTcell e-HFnewExt (HFcopy (domain) ,0) ; 

NFsizeCfte ,sizeof(CATEG0RY)+2*sizeof (double)) ; 
long l-(long)NFmemSet(e,sizeof (CATEGORY)) ; 

l+= sizeof (double) -l%sizeof (double) ; 

♦((double*) l)=cval; 

HFsig(e) ; 
return(e) ; 

} 

/////////////////////////////////////////////////////////////////////////////// 

static double HFP2C( HTcell mval ) // uses undocumented feature 

{ long l=(long)HFmemGet(mval,sizeof (CATEGORY)) ; 
l+= sizeof(double)-l%sizeof (double) ; 
return( *((double*)l) ); 

} 

/////////////////////////////////////////////////////////////////////////////// 

#define CHECK (n) \ 

if( !HFisExt(HFarg(n) ,HVdomain) ) HFerror( "Invalid argument" ) 
/////////////////////////////////////////////////////////////////////////////// 
#define FUICl(fun) \ 

HFnargsCheck(l); CHECK(l); \ 

HFreturn(newHFP(HVdomain ,fun(HFP2C(HFarg(l) ) ) ) ) 



/////////////////////////////////////////////////////////////////////////////// 

HFUIC( new, HCnop ) // create new elements 

{ HFnargsCheck(l) ; HFargCheckd ,D0H_FL0AT) ; 

HFreturn( newHFP(HVdomain,HFdouble(HFarg(l) ) ) ) ; 

} HFEHD 

/////////////////////////////////////////////////////////////////////////////// 

HFUHC( print, HCnop ) // display elements 

{ HFnargsCheck(l) ; CHECK(l); 

HFreturn( HFdouble(HFP2C(HFarg(D) ) ); 

} HFEHD 

/////////////////////////////////////////////////////////////////////////////// 

HFUHC( _plus, HCnop ) { // add elements 

double d=0.0; if( HVnargs==0 ) HFreturn( newHFP(HVdomain ,d) ); 
for( long i=l; i<=HVnargs; i++ ) { CHECK(i); d = d+HFP2C(HFarg(i) ) ; } 
HFreturn( newHFP(HVdomain,d) ); 

} HFEHD 



HFUHC( _mult, HCnop ) { // multiply elements 

double d=1.0; if( HVnargs==0 ) HFreturn( newHFP(HVdomain ,d) ); 
for( long i=l; i<=HVnargs; i++ ) { CHECK(i); d = d*HFP2C(HFarg(i) ) ; } 
HFreturn( newHFP(HVdomain,d) ); 

} HFEHD 

/////////////////////////////////////////////////////////////////////////////// 
HFUHC( sin, HCnop ) { FUHCKsin) } HFEHD // the Sin function 

HPR0C( expr = "hold(mfp: :print)" ) // convert to D0H_FL0AT 



Integrating directed roundings from the IEEE 754 standard, this module can be 
extended to implement a very fast fixed-precision interval arithmetic in Mu PAD. 

Refer to the directory demo/MFP/ on the CD-ROM for additional information. 



10.3 Numerics 

Since general purpose computer algebra systems, like M u PAD, emphasize the 
idea of symbolic computations, they often are weak in numerical calculations. 
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The concept of dynamic modules gives users a chance to come over this weakness 
by integrating fast arithmetic routines (e.g. as described mfp in section 10.2.2) 
or by interfacing special numeric libraries like IMSL and NAGC. 

10.3.1 Using the IMSL Library 

The IMSL^ C/C++ library (CNL) is a well known package for numerical cal- 
culations. By integrating IMSL algorithms into Mu PAD one can combine the 
power of IMSL with the strength of Mu PAD (symbolic computations) to solve 
mathematical problems. Furthermore, Mu PAD performs a flexible and comfort- 
able interface to your IMSL algorithms. 

The example below is trivial and is just mentioned to demonstrate the technique 
to integrate the IMSL library in Mu PAD. The example shows a module function 
to solve systems of linear equations: 



» module ( imsl ) : 

» imsl: :linsolve( 3, [[1,3,3] , [1,3,4] , [1,4,3]] , [1,4,-1] ); 
Solution, X of Ax = b 

12 3 

-2 -2 3 

[-2.0, -2.0, 3.0] 



To run this example you need a licensed version of the IMSL library. Change the 
source code lines 11-13 according to your need and set the shared library search 
path correspondently (see section 8.5.1). On our system, LD_LIBRARY_PATH 
must be set to: setenv LD .LIBRARY. PATH /mathsoft/ipt/lib/lib . Solaris 

1 /////////////////////////////////////////////////////////////////////////////// 

2 // MODULE: imsl — Interfacing the IMSL numeric library 

3 // AUTHOR: Andreas Sorgatz (andi@mupad.de) 

4 // DATE : 17. Dec. 1997 

5 /////////////////////////////////////////////////////////////////////////////// 

6 // Depending on the operating system, compiler and linker options must be set 

7 HHG( Solaris: coption = "-I/mathsoft/ipt/include" ) 

8 HHG( Solaris: loption = "-L/mathsoft/ipt/lib/lib . Solaris" ) 

9 HHG( Solaris: loption = "-limslcmath -Im -Insl -Isocket" ) 

10 #include <imsl.h> 

11 

12 /////////////////////////////////////////////////////////////////////////////// 

13 HFUHCC linsolve, MCnop ) // solve systems of linear equations 

14 { HFnargsCheck(3) ; // Check the input parameter 

15 MFargCheckd ,D0H_INT) ; HFargCheck(2 ,D0H_LIST) ; HFargCheck(3,D0M_LIST) ; 

16 

17 int n=HFint (MFarg(l) ) ; // number of row and columns 

18 HTcell mat=MFarg(2) , vec=HFarg(3) ; // the matrix amd the vector 

19 float *A = (float*) HFcmalloc(n*n*sizeof (float) ) ; // imsl matrix 

20 float *b = (float*) HFcmalloc( n*sizeof (float )) ; // imsl vector 



^Visual Numerics International, http://www.vni.com 
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21 

22 int i , j ; // convert the input 

23 for( i=0; i < n; i++ ) 

24 for( j=0; j < n; j++ ) A[i*n+j] = HFfloatC HFop(HFop(mat ,i) , j) ); 

25 for( i=0; i < n; i++ ) b[i] = HFfloat( HFop(vec,i) ); 

26 

27 float *x = imsl_f_lin_sol_gen( n, A, b, 0 ); // solve the system 

28 imsl_f_write_matrix( "Solution, x of Ax = b", 1, n, x, 0 ); 

29 MFcfree(A); HFcfree(b); 

30 if ( x==IULL ) HFerrorC "lo solution" ) ; 

31 

32 HTcell res = MFnewList(n) ; // convert the result 

33 for( i=0; i < n; i++ ) HFsetList( ftres, i, HFfloat (x[i] ) ); 

34 MFsigC res ); 

35 

36 HFcfree(x); 

37 HFreturn( res ) ; // return solution 

38 } HFEHD 



Refer to the directory demo/IMSL/ on the CD-ROM for additional information. 



10.3.2 Using the NAGC Library 

The NAG^ library is a widely known package for numerical calculations. First 
versions were only available in FORTRAN, but newer ones are also available as C 
libraries (NAGC). By integrating NAGC algorithms into MuPAD one can com- 
bine the power of NAGC with the strength of MuPAD (symbolic computations) 
to solve mathematical problems. Furthermore, MuPAD performs a flexible and 
comfortable interface to your NAGC algorithms. 

This example demonstrates a module function random which interfaces the 
NAGC random number generator and a function roots which calculates ap- 
proximations for all complex roots of a complex polynomial. Using NAGC is 
facilitated by the header file mnag.h which contains routines for data conversion 
between MuPAD and NAGC. 



» module (nagc) : // load the module 

» nagc: :random( 42, 4 ); // create lists of 

[0.585542118, 0.1859650411, 0.55882297, 0.1279809965] 

» nagc: :random( 17, 2 ); // random numbers 

[0.8293408721, 0.9001032522] 

» nagc::roots( poly(2*x"3 +5*x"2 +3) ); // find complex roots 

[-2.705001171 +0.00000000000000005551115123 I, 
0.1025005859 -0.7375784977 I, 0.1025005859 +0.7375784977 I] 



^The Numerical Algorithms Group Ltd. , http : //www . nag .co.uk 
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To run the example above you need a licensed version of the NAGC library. 
Change the source code lines 7-13 according to your need. 



1 

2 

3 

4 

5 

6 

7 

8 
9 

10 

11 

12 

13 

14 

15 

16 

17 

18 

19 

20 
21 
22 

23 

24 

25 

26 

27 

28 

29 

30 

31 

32 

33 

34 

35 

36 

37 

38 

39 

40 

41 

42 

43 

44 

45 

46 

47 

48 

49 

50 

51 

52 

53 

54 

55 

56 

57 

58 

59 



/////////////////////////////////////////////////////////////////////////////// 
// MODULE: nagc — Interfacing the lAGC numeric library 
// AUTHOR: Andreas Sorgatz (andiQroupad.de) 

// DATE : 31. Mar. 1998 

/////////////////////////////////////////////////////////////////////////////// 

// Depending on the operating system, compiler and linker options must be set 



MMG( Solaris: coption = 
MMG( Solaris: loption = 
MMG( Solaris: loption = 
MMG( Solaris: linker =* 



MMG( i386 
MMG( i386 
MMG( i386 



coption = 
loption = 
loption = 



••-I/usr/local/MATH/IAGC/include" ) 
••-L/usr/local/MATH/IAGC -Inagc" ) 

"“Im /usr/lib/libc.so.l" ) 

"Id -G" ) 

"-I/Biwianka/user/andi/IAGC/linux/include" ) 
"-L/wiwianka/user/andi/IAGC/linux/lib -Inagc" ) 
"-Im" ) 



#include "mnag.h" // a simple MuPAD interface to lAGC 

extern "C" { // lAGC header files 

#ifdef linux 

# include <nagg05 . h> 

# include <nagc02.h> 
ffelse 

# include <Hag/nagg05 . h> 

# include <Nag/nagc02 . h> 

#endif 

} 

/////////////////////////////////////////////////////////////////////////////// 

// random( InitValue, lumOfValue ) 

// HAG data types 

// exactly two arguments are expected 
// range := O..MFarg(l) 

// number := MFarg(2) random values 
// converts DOM.IIT to Integer 



MFUHC( random, MCnop ) 

{ Integer i, num; 
MFnargsCheck(2) ; 
MFargCheck(l,DOM_INT) ; 
MFargCheck(2,D0M_INT) ; 
num = HHintegerC MFarg(2) ) ; 



g05cbc( MHinteger (MFarg(l) ) ); // initializes remdom number generator 

MTcell list = MFnewList(num) ; // creates a MuPAD list 

for( i=0; i < num; i++ ) // fills list with random MuPAD numbers 

HFsetListC ftlist, i, HHdouble(g05cac() ) ); 

MFsig(list) ; // calculates the signature of the list 

MFreturn(list) ; // returns the MuPAD list 

} MFEHD 



/////////////////////////////////////////////////////////////////////////////// 

MFUNCC roots, MCnop ) // roots ( ComplexPolynomial ) 

{ MFnargsCheck(l) ; 

MFargCheck(l,DOM_POLY) ; 

Integer degree = MFdegPoly( HFarg(l) ); 



// Convert the MuPAD polynomial to the lAGC representation and allocate 
// the vector for the Megree’ complex roots of this polynomial. 

Complex *poly = (Complex*) MHcomplexPoly ( MFarg(l) ); 

Complex *roots = (Complex*) MFcmalloc( degree*sizeof (Complex) ) ; 



c02afc( degree, poly, TRUE, roots, MNfailO ); // find all complex roots 



MFcfree( poly ); 

MTcell result = MNcomplexList( roots, degree ); 
MFcfree( roots ); 

MFreturn( result ) ; 

} MFEHD 



// free the HAGC polynomial 
// Convert roots to MuPAD 
// free the HAGC roots 



Refer to the directory demo/NAGC/ on the CD-ROM for additional information. 
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10.4 Arbitrary Precision Arithmetic 

10.4.1 Using the GMP Librciry 

This example demonstrates the integration of algorithms written by use of the 
GMP library (see appendix A. 1.4). The usage of GMP is facilitated by the 
header file mgmp.h which contains routines for data conversion between the 
GMP and PARI (used by Mu PAD) representation of arbitrary precision integer 
numbers. The example module can be used as follows: 



» module (gmp) : // load the module 

» num:= 1234567890123456789012345678901234567890: 

» gmp::mult( 42, num ); // multiply with GMP 

51851851385185185138518518513851851851380 

» */. / 42 -num; 



0 



The source code shows how easy it is to use GMP within dynamic modules: 



1 /////////////////////////////////////////////////////////////////////////////// 

2 // MODULE: gmp — Interfacing the GIU HP library 

3 // AUTHOR: Andreas Sorgatz (emdi@mupad.de) 

4 // DATE : 24. Mar. 1998 

5 /////////////////////////////////////////////////////////////////////////////// 

6 

7 MMG( Solaris: loption = "-Lgmp . Solaris -Igmp -Im" ) // the GMP and math library 

8 HHG( i386: loption = "“Lgmp.i386 -lgmp -Im" ) // the GMP and math library 

9 

10 ttinclude "mgmp.h" // a simple MuPAD interface to GMP 

11 

12 /////////////////////////////////////////////////////////////////////////////// 

13 MFUUC ( mult, HCnop ) 

14 { MFnargsCheck(2) ; 

15 if( !HFisInteger(HFarg(l)) il !HFisInteger(HFarg(2) ) ) // accept integers 

16 MFerrorC "Integer expected" ); 

17 

18 mpz_t gmplntl, gmplnt2, gmplnt3; 

19 

20 MGintegerC gmplntl, HFarg(l) ); 

21 MGinteger( gmplnt2, HFarg(2) ); 

22 

23 mpz_init( gmplnt3 ); 

24 mpz.mul ( gmplnt3, gmplntl, gmplnt2 ); 

25 mpz_clear( gmplntl ) ; 

26 mpz_clear( gmplnt2 ); 

27 

28 HTcell result = MGintegerC gmplnt3 ) ; 

29 mpz_clear( gmplnt3 ) ; 

30 HFreturnC result ); 

31 } HFEHD 



// Declare some GMP numbers 

// Convert HuPAD integers 
// to GMP integer numbers 

// Initialize a GMP number to 
// store gmplntl ♦ gmplnt2 
// Free the GMP inter numbers 
// which are not longer needed 

// Convert to a HuPAD integer 
// Free it GMP representation 
// return the result to HuPAD 



Refer to the directory demo/GMP/ on the CD-ROM for additional information. 
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10.5 Polynomial Computations 

This section demonstrates module applications for very efficient computations 
on polynomials. The special purpose computer algebra system Singular is used 
to accomplish very fast Grobner basis computations, Magnum and NTL can 
be used for factoring polynomials over finite fields and the ring of the integers 
and last but not least the GB and RealSoIving system enable users to compute 
large Grobner basis and find and classify real roots of very huge polynomials. 



10.5.1 Polynomial Factorization with MAGNUM 

The Magnum library (see appendix A. 1 . 5 ) provides very fast factorization al- 
gorithms for univariate polynomials over a residue class ring Fp, with p a prime 
less than 2^^. The example below demonstrates how this can be used within 
Mu PAD to factor a univariate polynomial over F65437. 



» module (magnum) : 

» P:= poly( x‘‘200 + x + 1, [x] , IntMod(65437) ): 

» magnum: : irreducible (P) ; 

FALSE 

» time( magnum: : fact or (P) ); 

30470 

» magnum: : doc ("factor") : 

factor - Factorizes a univariate polynomial over IntMod(p) 

[...] 



The complete source code of the Magnum module interface -including the func- 
tions factor, gcd, irreducible, issqrf ree and sqrf ree- only contains about 
220 lines of C++ code - including comments. Special to this example module 
is, that the Magnum library is implemented by use of templates. 



1 

2 
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4 
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7 
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17 



/♦ HODUL : magnum. C - Module Interface for Magnum (refer to the README) ♦/ 
/* AUTHOR : Paul Zimmermann (Paul.Zimmermann@loria.fr) ♦/ 
/* Andreas Sorgatz (amdi@uni-paderborn.de) ♦/ 
/* CHANGED: 24/03/98 ♦/ 
/* This is the HuPAD interface of the package Magnum. It is written in C++ */ 
/* and must be compiled to a dynamic module by using the module generator ♦/ 
/♦ mmg. For further information refer to the script ’magnum. sh’. ♦/ 
/* Wolfgang Roth’s (roth@math.uni-mamnheim.de) package ’magnum’ provides */ 
/* fast factorization algorithms for polynomials over fields Fp with p is */ 
/* prime. ’magnum. tar .gz’ is available via amonymous ftp at: ♦/ 
/* ftp://obelix.statistik.uni-mamnheim.de/public/magnum */ 



/Hiif^iilf^fili***ilt^fiif***************************************************************/ 

MMG( Solaris: coption = "-Imagnum. solaris/include" ) 

MMG( Solaris: loption = "-Lmagnum.solaris/libraury -Imagnum -Im" ) 

MMG( i386: coption = "-Imagnum. i386/include" ) 

MMG( i386: loption = "-Lmagnum . i386/library -Imagnum -Im" ) 
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18 #undef overflow // conflicting PARI definement 

19 #include "magnum/Prime . H" 

20 #include "magnum/FpPolynom.H" 

21 #include "magnum/FpPolynom.Set .H" 

22 

23 ///////////////////////////////////////////////////////////////////////////// 

24 // Conversion routines for polynomials - Hagnum < — > HuPAD ////////////////// 

25 ///////////////////////////////////////////////////////////////////////////// 

26 

27 ///////////////////////////////////////////////////////////////////////////// 



28 #define COIVERT(arg,magPoly,mupUndets,mupField, prime, expo, mode) \ 

29 /♦ Check if ’arg’ is a valid polynomial, convert it into HuPAD list ♦/ \ 

30 /* representation, collect information for the further conversion. */ \ 

31 HTcell mupList, mupUndets, mupField; \ 

32 long prime, expo; \ 

33 if( !mupPolyCheck(arg, mupList , mupUndets, mupField, prime, expo, mode) ) \ 

34 HFreturnC HFcopy(HVfail) ); \ 

35 \ 

36 /* Create a Hagnum polynomial with the collected information \ 

37 FpPolynom magPolyC (Prime) prime ) ; \ 

38 mupPoly2mag( mupList , prime , magPoly ) ; \ 

39 HFfree( mupList ); \ 

40 



41 ///////////////////////////////////////////////////////////////////////////// 



42 


static int mupPolyCheck ( HTcell 


mupPoly, 


// II 


43 


HTcell 


ftmupList , 


// OUT 


44 


HTcell 


ftmupUndets , 


// OUT 


45 


HTcell 


ftmupField, 


// OUT 


46 


long 


ftprime , 


// OUT 


47 


long 


ftexpo , 


// OUT 


48 


int 


Exit0nError=0 


// II 


49 


) 






50 


{ int error = 0; 







51 // Check if ’mupPoly’ is an univariate polynomial over the finite field 

52 // Fp with p is prime and less than 2‘'16. Other polynomials cannot be 

53 // handled by Hagnum. 

54 if( !HFisPolynom(mupPoly) ) { 

55 if( ExitOnError ) HFerrorC "Polynomial expected" ); 

56 return ( 0 ) ; 

57 } 

58 mupUndets = HFop( mupPoly, 1 ); 

59 if( HFnops (mupUndets) != 1 ) { 

60 if ( ExitOnError ) HFerror( "Polynomial must be univariate" ) ; 

61 return( 0 ) ; 

62 } 

63 mupField = HFop( mupPoly, 2 ); 

64 if ( !HFisExpr (mupField, "IntHod") I I HFnops (mupField) != 2 ) { 

65 if( ExitOnError ) HFerror( "Polynomial must be of type ’lntHod(p) ’") ; 

66 return ( 0 ) ; 

67 } 

68 HTcell mprime = HFop(mupField,l) ; 

69 if( HFlt (mprime ,HVzero) M HFgt (mprime ,HFlong(65535) ) ) { 

70 if( ExitOnError ) HFerror( "IntHod(p), p out of range" ); 

71 return( 0 ) ; 

72 } 

73 prime = HFlong( HFop(mupField , 1) ); 

74 expo = 1 ; 

75 HTcell result = HFcalK "isprime", 1, HFlong(prime) ); 

76 if( !HFisTrue (result) ) { 

77 HFfree( result ); 

78 if( ExitOnError ) HFerror( "IntHod(p), p must be prime" ); 

79 return ( 0 ) ; 

80 } 

81 HFfree( result ); 

82 // Convert the HuPAD polynomial into its list representation, which is 

83 // much easier to analyse to convert it into a Hagnum polynomial. 
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mupList = MFcalK "poly21ist'' , 1, HFcopy(mupPoly) ); 
return ( 1 ) ; 

} 

///////////////////////////////////////////////////////////////////////////// 

static int mupPoly2mag ( HTcell mupList, // IH 

long prime, // II 

FpPolynom ftmagPoly // OUT 

) 

{ // Convert the list representation of a MuPAD polynomial into a Magnum 
// polynomial. Use ’prime’ for this. 

MTcell monom; 

long coeff, expo, length = MFnops (mupList) ; 
for( int pos = 0; pos < length ; pos++ ) { 
monom = HFgetList( ftmupList , pos ); 
coeff = HFlongC MFgetList(ftmonom,0) ); 
if( coeff < 0 ) coeff += prime; 
expo = HFlong( HFgetList(&monom,l) ); 

magPoly += FpPolynom( magPoly .descriptor , (Fp)coeff, expo ); 

} 

return( 1 ) ; 

} 

///////////////////////////////////////////////////////////////////////////// 

static HTcell magPoly2mup ( const FpPolynom ftmagPoly, //IN 

MTcell ftmupUndets, // IN 

HTcell ftmupField // IN 

) 

{ HTcell mupList, mupPoly, monom; 
long pos = 0; 

// First create a list representation of the MuPAD polynomial. Then 
// convert is into a native polynomial by using ’poly’. 
mupList = HFnewList( magPoly .length () ); 

for( FpPolynom_Iterator x_iter(magPoly) ; x_iter(); ++x_iter ) { 
monom = HFnewListC 2 ); 

HFsetListC ftmonom, 0, MFlong( (long)x_iter( ) ->factor) ); 

MFsetListC ftmonom, 1, HFlong( (long)x_iter()->poHer) ); 

HFsetList( ftmupList, pos++, monom ); 

} 

return( HFcall("poly'' ,3, mupList ,MFcopy(mupUndets) ,HFcopy (mupField) ) ) ; 

} 

///////////////////////////////////////////////////////////////////////////// 

static long magPolyListLen ( const FpPolynom.List ftmagPolyList ) 

{ long n = 0; // How many polynomials are in this list? 

for( FpPolynom_List_Iterator l.iter (magPolyList) ; l_iter(); ++l_iter ) 
n += l_iter()->set 0 . sizeO ; 
returnC n ) ; 

} 

///////////////////////////////////////////////////////////////////////////// 

static HTcell magPolyList2mup ( const FpPolynom_List ftmagPolyList, // IN 

HTcell ftmupUndets, // IN 

HTcell ftmupField // IN 

) 

{ FpPolynom_List_Iterator l_iter( magPolyList ) ; 

HTcell mupList, mupPoly; 

long pos = 1 ; 

// Create a MuPAD list with the first element is the integer factor. 
mupList = MFnewList( magPolyListLen (magPolyList) *2+1 ) ; 

HFsetList( ftmupList, 0, HFlong( (long) magPolyList .factor) ); 

// Insert pairs (poly , exponent) into the factor list. 
if( l_iter() ) do { 

FpPolynom_Set_Iterator s_iter( l_iter()->set() ); 
if( s_iter() ) do { 

mupPoly = magPoly2mup( s_iter()->polynom() ,mupUndets , mupField ); 
MFsetList( ftmupList, pos++, mupPoly ); 

HFsetList( ftmupList, pos++, MFlong( (long)l_iter()->power) ); 
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150 } while( (++s_iter)() ); 

151 } while( (++l_iter)() ); 

152 HFsig ( mupList ) ; 

153 return ( mupList ) ; 

154 } 

155 

156 ///////////////////////////////////////////////////////////////////////////// 

157 // HuPAD interface functions - these are visible in HuPAD /////////////////// 

158 ///////////////////////////////////////////////////////////////////////////// 

159 

160 ///////////////////////////////////////////////////////////////////////////// 

161 HFUICC id, HCnop ) 

162 { HFnargsCheck(l); 

163 COIVERK MFarg(l), magPoly, mupUndets, mupField, prime, expo, 1 ); 

164 HFreturn( magPoly2mup( magPoly, mupUndets, mupField ) ); 

165 } HFEID 

166 ///////////////////////////////////////////////////////////////////////////// 

167 HFUHC( factor, HCnop ) 

168 { HFnargsCheck(l) ; 

169 COIVERK MFarg(l), magPoly, mupUndets, mupField, prime, expo, 0 ); 

170 FpPolynom_List magPolyList ; 

171 factorize ( magPolyList, magPoly ); 

172 MTcell tmp = magPolyList2mup( magPolyList, mupUndets, mupField ); 

173 HFreturnC tmp ) ; 

174 } HFEID 

175 ///////////////////////////////////////////////////////////////////////////// 

176 HFUICC gcd, HCnop ) 

177 { ifC HVnargs == 0 ) HFreturnC HFcopyCHVzero) ); 

178 ifC HVnargs == 1 ) HFreturnC HFcopyCHFargCl) ) ); 

179 COIVERTC HFargCl), magPoly, mupUndets, mupField, prime, expo, 0 ); 

180 forC long i = 2; i <= HVnargs; i++ ) { 

181 COIVERTC HFargCi), magPoly2, mupUndets2,mupField2,prime2,expo2, 0 ); 

182 ifC prime != prime2 || IHFequalCmupUndets ,mupUndets2) ) 

183 HFreturnC HFcopyCHVfail) ); 

184 ifC magPoly == magPoly2 ) continue; 

185 magPoly = gcdC magPoly, magPoly2 ); 

186 } 

187 HFreturnC magPoly2mupC magPoly, mupUndets, mupField ) ); 

188 } HFEID 

189 ///////////////////////////////////////////////////////////////////////////// 

190 HFUICC irreducible, HCnop ) 

191 { HFnargsCheckCl) ; 

192 COIVERTC HFargCl), magPoly, mupUndets, mupField, prime, expo, 0 ); 

193 ifC magPoly . is.irreducibleC) ) { HFreturnC HFcopyCHVtrue ) ); } 

194 else { HFreturnC HFcopyCHVfalse) ) ; } 

195 } HFEID 

196 ///////////////////////////////////////////////////////////////////////////// 

197 HFUICC issqrfree, HCnop ) 

198 { HFnargsCheckCl) ; 

199 COIVERTC HFargCl), magPoly, mupUndets, mupField, prime, expo, 0 ); 

200 ifC magPoly .is_squ£irefreeC) ) { HFreturnC HFcopyCHVtrue ) ); } 

201 else { HFreturnC HFcopyCHVfalse) ) ; } 

202 } HFEID 

203 ///////////////////////////////////////////////////////////////////////////// 

204 HFUICC sqrfree, HCnop ) 

205 { HFnargsCheckCl); 

206 COIVERTC HFargCl), magPoly, mupUndets, mupField, prime, expo, 0 ); 

207 FpPolynom_List magPolyList ; 

208 squarefreeC magPolyList, magPoly ); 

209 HFreturnC magPolyList2mupC magPolyList, mupUndets, mupField ) ); 

210 } HFEID 

This module was developed in cooperation with Paul Zimmermann, Inria Lor- 
raine, Nancy, France. Refer to the directory demo /MAGNUM/ on the CD-ROM 
for more information. 
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10.5.2 Using the NTL Library 

The C++ package NTL [2] provides very fast factorization algorithms for uni- 
variate polynomials over the integers and more (see appendix A. 1.7). 

The usage of NTL is facilitated by the file mntl.h which contains routines for 
data conversion between NTL and MuPAD. The example below demonstrates 
the factorization of a univariate polynomial by use of the dynamic module ntl. 



» module (ntl ) : 

» ntl::gcd( 211111111121111111112, 112 ); 

8 

» P:= poly( x"200 + x + 1, [x] ): 


// load the module 
// compute a gcd 


// factor a polynomial 


» time( (L:=ntl: :factor(P) ) ); 


// over the integers 


36330 


// it^s fast 


» P -op(L,2)*op(L,4); 




o 

0 

1 — 1 
X 

1 1 


// and it’s correct ;-) 



The module main source code file of this example module is listed below: 

1 /:ti^i:ilfitHlli:tf*iHf^f^f:t‘***************i‘******i‘****************************************/ 

2 /♦ FILE : ntl.C - A simple demo using the HTL library */ 

3 /* AUTHOR : Andreas Sorgatz (euidi@uni-paderborn.de) ♦/ 

4 /* DATE ; 27/03/1998 */ 

5 /:tiilf:itHt‘ii*t^i^Hlf^itiiilf*^t**********************************************************/ 

6 HMG( Solaris: coption = "-Inti . Solaris” ) 

7 MHG( Solaris: loption = "-Lntl . Solaris -Inti -Im" ) 

8 HHG( i386: coption = "-Intl.i386" ) 

9 HMG( i386: loption = "-Lntl.i386 -lntl -Im" ) 

10 

11 #include "mntl.h" // a simple HuPAD interface to HTL 

12 

13 ///////////////////////////////////////////////////////////////////////////// 

14 MFUHC( gcd, HCnop ) // gcd for integers 

15 { ZZ a, b, prod; 

16 HTcell res; 

17 HFnargsCheck(2) ; 

18 if( !mupad2ntl(a, HFarg(D) ) HFerror( "Invalid argument" ); 

19 if( !mupad2ntl(b , MFarg(2)) ) HFerror( "Invalid argument" ); 

20 GCD(prod, a, b) ; 

21 if( !ntl2mupad(prod , res) ) HFerrorC "Cannot convert result" ); 

22 HFreturn( res ) ; 

23 } MFEND 

24 

25 ///////////////////////////////////////////////////////////////////////////// 

26 MFUHC( mult, HCnop ) // multiplication for integers 

27 { ZZ a, b, prod; 

28 HTcell res; 

29 HFnargsCheck(2) ; 

30 if( !mupad2ntl(a, HFarg(D) ) HFerror( "Invalid argument" ); 

31 if( !mupad2ntl(b , HFarg(2)) ) HFerrorC "Invalid argument" ); 

32 mulCprod , a, b) ; 

33 if( !ntl2mupad(prod , res) ) HFerrorC "Cannot convert result" ); 

34 HFreturnC res ) ; 

35 } HFEHD 

36 
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37 ///////////////////////////////////////////////////////////////////////////// 

38 HFUIC( factor, NCnop ) // Factors polynomials P(x) 

39 { MFnargsCheck(l); 

40 HFargCheck (1 , D0M_P0LY) ; 

41 ZZX poly = mupadPoly2ntlPoly( MFarg(l) ); 

42 vector (pair (ZZX , long) ) fac; 

43 ZZ c ; 

44 factor (c, fac, poly); 

45 MFreturn( ntlPolyFactorList2mupad(c , fac, HFident ("x") ) ); 

46 } HFEID 



Refer to the directory demo/NTL/ on the CD-ROM for additional information. 



10,5.3 The GB and RealSolving System 

GB computes Grobner basis in an extremly efficient way whereas RealSolving 
can be used to classify real roots of huge polynomials. This module application 
has been (and still is) developed by Fabrice Rouiller and Jean-Charles Faugere. 
Also refer to section A. 1.3. 

Refer to the web page http://www.loria.fr/'^rouillie/MUPAD/gbrGso.html of 
the developers for latest information. 

The modules gb, rs and rsu allow users to use GB and RealSolving from within 
MuPAD. Before using them, the user has to configure where both systems are 
installed and on which hosts of a heterogenious network each them is to be 
started. This can be done as follows: 



// The MuPAD architecture of the local host (current kernel) is: 
ARCH:= sysname(Arch) : 

READ_PATH:= READ.PATH, MDM_PATH. "/GBRSOLVE/modules." . ARCH: 

// The homes of GB and RealSolving on the CD-ROM are defined as: 

GBHome := MDM_PATH. "/GBRSOLVE/" . ARCH: gb_machine := 

RSHome := GBHome: rs_machine := gb_machine: 

RSUHome:= RSHome: rsu_machine:= rs_machine: 

// Loads the dynamic modules which interface GB and RealSolving: 
module(gb): module(rs): module(rsu): 

// Display the interface functions available with these modules: 
info(gb): info(rs): info(rsu): 



The following example now demonstrates a typical session using both systems: 
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// Some more convenient interface functions to GB & RealSolving: 

gbgb : =proc ( Ipoly , vv ) 

local 111, lip; 

begin GbHome : =GBHome ; 

gb: : createConnection("serveur_t DMP Dexp INT" ,gb_machine) ; 

111 :=map (Ipoly, poly, vv) ; gb: :Groebner(lll) ; 
llp:=gb: :ReceiveLDpol() ; gb: : closeConnectionO ; 
return(llp) ; 
end^proc : 

r srur : =proc ( Ipoly ) 
local 111, lip; 
begin GbHome : =RSHome ; 

rs: : createConnectionC'ServerRS" ,rs_machine) ; 
rs: : RSTablelnit (Ipoly) ; rs: :ReceiveMT() ; 
rs : :RUR() ; llp:=rs : :ReceiveRUR( Cx] ) ; 
rs : : closeConnectionO ; 
return(llp) ; 
end_proc : 

// The defintion of a system of multivariate polynomials: 
Fl:=2*x‘'2+2*y^2+2*z^2+2*t^2+2*u^2+v^2-v: 

F2 : =2*x*y+2*y*z+2*z*t+2*t*u+2*u*v-u : 

F3 : =2*x*z+2*y*t+2*z*u+u‘'2+2*t*v-t : 

F4 : =2*x*t+2*y*u+2*t*u+2*z*v-z : 

F5 : =t '‘2+2*x*v+2*y*v+2*z*v-y : 

F6 : =2*x+2*y+2*z+2*t+2*u+V”l : 

10:=[F1,F2,F3,F4,F5,F6] : 
va:=[x,y ,z,t ,u,v] : 

base:=gbgb(10,va) : // Computes a groebner basis 

rur :=rsrur(base) : // Computes a rational univariate representation 



The source code of the modules gb, rs and rsu as well as of both systems itself 
is not available. For questions and comments please contact the authors via 
email at Fabrice.Rouillier@loria.fr and jcf@calfor.lip6.fr. 

Refer to the directory demo/GBRSOLVE/ on the CD-ROM for more information. 



10.5.4 Interfacing Singular 

Singular is a computer algebra system for commutative algebra, algebraic geo- 
metry and singularity theory and especially provides very fast algorithms for 
polynomial computations (see appendix A. 1.9). 

The simple library package sing. mu performs a user friendly link between 
Mu PAD and the Singular system to accomplish very efficient computation of 
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Grobner basis. This link is based on the mp module described in section 10.6.2.^ 

The following example shows the Mu PAD solution for problem 6 of the ISSAC’97 
system challenge (computation of a lexicographical Grobner basis - see [38] [39] 
as demonstrated on ISSAC’97. See also [41] [42]. Note, that this is just a 
prototype. 



» readC'sing.mu") : 

» Ia:= Ideal( poly(3*x''8+x"2*y‘'2*z"2, [x,y,z], IntMod(32003) ) , 

poly(2*x"3*y^2*z"2+y"7+4*y"5*z+5*y^2*z"4, [x,y,z], IntMod(32003) ) ): 
» Ra:=sing: : std( la ); 

[...] 

// Problem 6 of ISSAC^97 System Challenge 
» pl:= poly(8*w^2+5*w*x-4*w*y+2*w*z+3*w+5*x^2+2*x*y-7*x*z-7*x+7*y^2 
-8*y*z-7*y+7*z"2 -8*z+8, [w,x,y,z]): 

» p2 : = poly (3*w"2-5*w*x-3*w*y-6*w*z+9*w+4*x"2+2*x*y-2*x*z+7*x+9*y"2 
+6*y*z+5*y+7*z"2+7*z+5, [w,x,y,z] ) : 

» p3:= poly(-2*w"2+9*w*x+9*w*y-7*w*z-4*w+8*x"2+9*x*y-3*x*z+8*x+6*y"2 
-7*y*z+4*y~6*z"2+8*z+2, [w,x,y,z] ) : 

» p4:= poly(7*w^2+5*w*x+3*w*y-5*w*z-5*w+2*x^2+9*x*y-7*x*z+4*x-4*y^2 
-5*y*z+6*y-4*z^2-9*z+2, [w,x,y,z] ) : 

» Rb:=sing: : stdfglmC Ideal (pi ,p2,p3,p4) ); 

[...] 



The dynamic module mp as well as the Singular system are only loaded on 
demand. Details about this project can be found in the article Connecting 
MuPAD and Singular with MP [3]. 

1 /////////////////////////////////////////////////////////////////////////////// 

2 // FILE : sing. mu — Algebraic Geometry and Singularity Theory with Singular 

3 // AUTHOR : Andreas Sorgatz (andiQuni-paderborn.de) 

4 // DATE : 25. Mar. 1998 

5 /////////////////////////////////////////////////////////////////////////////// 

6 

7 procO 

8 begin 

9 sing := domain ("sing") : 

10 sing:: info := "’sing’: Algebraic Geometry and Singularity Theory with Singular": 

11 sing: : interface := { hold(std) , hold(stdfglm) , hold(close), hold(write) }: 

12 

13 sing:: host:* "localhost"; // host at which to start Singular 

14 sing::sing:* "singular -b" ; // command syntax to start Singular 

15 sing::mp :* FAIL: // handle for the dynamoc module mp 

16 sing::link:* 0; // handle of the HP link to Singular 

17 

18 /////////////////////////////////////////////////////////////////////////////// 

19 // Load the dynamic module ’mp’ and launch ’Singular’ if necessary //////////// 

20 sing: : launch := procO 

21 begin 

22 if( sing: :mp = FAIL ) then sing::mp:* moduleC'mp") : end_if; 

®This modules uses ssh to launch Singular. Thus ssh must be installed and correctly 
configured on your system. Ask your system administrator how to do this. 
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23 if( sing::link= 0 ) then sing::link:= (sing: :mp) : :open( 

24 "-MPtransp", "TCP", "-HPmode", "launch", 

25 "-HPhost" , sing::host, "-HPapplication" , sing: : sing 

26 ) ; 

27 end_if; 

28 if( sing: : link = 0 ) then errorC "Sorry, cannot launch Singular" ); end_if; 

29 end_proc : 

30 /////////////////////////////////////////////////////////////////////////////// 

31 // Terminate Singular and close the HP link /////////////////////////////////// 

32 sing: :close:= procO 

33 begin 

34 if( sing: :link <> 0 ) then 

35 (sing: :mp) : :write( sing::link, "HPtcp:quit" ); 

36 (sing: :mp) : : close( sing::link ); 

37 sing: : link := 0 ; 

38 end_if: 

39 nullO; 

40 end_proc : 

41 /////////////////////////////////////////////////////////////////////////////// 

42 // Send an command or object to Singular and return the result //////////////// 

43 sing: :write:= procO 

44 begin 

45 sing: : launchO ; // lauch Singular if necessary 

46 (sing: :mp) : :write( sing: : link, argsO ); 

47 (sing: :mp) : :read( sing: :link ); 

48 end_proc: 

49 /////////////////////////////////////////////////////////////////////////////// 

50 // Compute a Groebner Basis (LexOrder) using the standard algorithm /////////// 

51 sing: :std:= proc( ) 

52 begin 

53 sing: : launchO ; // lauch Singular if necessary 

54 (sing: :mp) : :write( sing::link, Std(argsO) ); 

55 (sing: :mp) : :read( sing::link ); 

56 end_proc: 

57 /////////////////////////////////////////////////////////////////////////////// 

58 // Compute a Groebner Basis (LexOrder) using a faster algorithm /////////////// 

59 sing: :stdfglm:= proc( ) 

60 begin 

61 sing: : launchO ; // lauch Singular if necessary 

62 (sing: :mp) : :write( sing::link, StdFglm(args() ) ); 

63 (sing: :mp) : :read( sing: :link ); 

64 end_proc : 

65 TRUE : 

66 end_proc(): 

Refer to the directory demo/SINGULAR/ as well as demo/MP/ on the CD-ROM 
for additional information. 

The interaction between Mu PAD and Singular using MP was realized in co- 
operation with Olaf Bachmann and Hans Schonemann from the Zentrum fiir 
Computeralgebra, Universitat Kaiserslautern, Germany. 



10.6 Interprocess Communication Protocols 



This section demonstrates the integration of interprocess communication (IPC) 
protocols into Mu PAD via dynamic modules by using the following packages: 
ASAP, MP, PVM. 
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10.6.1 The ASAP Protocol 

ASAP is an efficient and handy IPC protocol to transfer mathematical data 
(see appendix A. 1.2). The module described here does not make use of all the 
special features of ASAP but demonstrates the simpliest way to integrate IPC 
protocols via dynamic modules into MuPAD. 

The example below shows two MuPAD kernels started on different hosts of the 
Internet. The upper one is started as a computation server whereas the second 
kernel distributes jobs, collects their results and displays them. 



hostname ; mupad -S 




loria.loria.fr 




» info( module(asap) ): 




Module: *asap* created on 25. Mar. 98 by mmg R- 


-1.3.0 


Interface: 




asap::doc, asap: :openAsClient , asap: :openAsServer, I 


asap::recv, asap:: send, asap: : terminate I 


» asap: :openAsServer("loria", 4711,"") : # 


install server # 


» job:= asap: :recv() : 


# receive job # 


» res:= eval( text2expr( job) ): 


# execute job # 


» asap::send( expr2text (res) ): 


# send result # 


andi> 




hostname ; mupad -S 




poisson . uni-paderborn . de 




» module (asap) : 




» asap: :openAsClient("loria. loria.fr", 4711,"") : # connect # I 


» asap::send( "diff (sin(x) , x)" ): 


# send job # 


» text2expr( asap: : receive () ); 


# get result # 


cos(x) 




» asap : : terminate ( ) : 


# disconnect # 


» quit : 




andi> 





At time, character strings are used to transfer data. This is not as efficient 
as binary coded transfer but very easy to handle. Using the MuPAD functions 
text2expr, expr2text and system a prototype of a full featured IPC can be 
developed on the MuPAD language level. After that, string communication may 
be subsequently replaced by more efficient methods to transfer MuPAD data in 
a binary format. The complete source code of the ASAP module is: 

1 /////////////////////////////////////////////////////////////////////////////// 

2 // MODULE: asap.C — An example of integrating IPC protocols into MuPAD 

3 // AUTHOR: Andreas Sorgatz (andiQuni-paderborn.de) 

4 // DATE : 25. Mar. 1998 

5 /////////////////////////////////////////////////////////////////////////////// 

6 MMG( attribute = "static" ) // the module must not be displaced 

7 
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8 

9 

10 

11 

12 

13 

14 

15 

16 

17 

18 

19 

20 
21 
22 

23 

24 

25 

26 

27 

28 

29 

30 

31 

32 

33 

34 

35 

36 

37 

38 

39 

40 

41 

42 

43 

44 

45 

46 



MHG( Solaris: coption = 
HHG( Solaris: loption = 
MMG( i386: coption = 
MMG( i386: loption = 



-lasap . Solaris" ) 

-Lasap . soleoris -lASAP -Insl -Isocket" ) 
-lasap. i386" ) 

-Lasap. i386 -lASAP" ) 



extern "C" { 

ftinclude "asap.h" // include definitions of ASAP 

} 

static ASAPconn.t* c; //to store the hamdle of a link 



/////////////////////////////////////////////////////////////////////////////// 

HFUHC( openAsServer , HCnop ) 

{ c = ASAPaccept( HFstring(HFarg(l) ) , HFint (HFarg(2) ) , HFstring(HFarg(3) ) ); 

HFreturnC HFcopy (HVnull) ) ; 

} HFEND 

/////////////////////////////////////////////////////////////////////////////// 

HFUHC( openAsClient , HCnop ) 

{ c = ASAPcontact( HFstring(HFarg(D) , HFint (HFarg(2) ) , HFstring(HFarg(3) ) ); 

HFreturnC HFcopy (HVnull) ); 

} HFEND 

/////////////////////////////////////////////////////////////////////////////// 

HFUNCC terminate, HCnop ) 

{ ASAPterminateC c ); 

HFreturnC HFcopy (HVnull) ) ; 

} HFEND 

/////////////////////////////////////////////////////////////////////////////// 

HFUNCC send, HCnop ) 

{ char* s = HFstring(HFargCl) ) ; 

ASAPsendBinaryC c->normal, s, strlen(s) ); 

ASAPflushC c->normal ) ; 

HFreturnC HFcopy (HVnull) ); 

} HFEND 

/////////////////////////////////////////////////////////////////////////////// 

HFUNCC recv, HCnop ) 

{ static char buffer [512]; 

ASAPnextTokenC c->normal ) ; 

ASAPgetBinaryC c->normal, buffer ); 

HFreturnC HFstringCbuffer) ) ; 

} HFEND 



The ASAP module may be used as transportation layer for OpenMath.^ Us- 
ing a dynamic module, users themselves can exchange the transportation layer 
whenever they want by whatever they want. Furthermore, changes of the pro- 
tocol do not result in changes of the Mu PAD kernel. Module updates can be 
made available in short time and independently from kernel updates. 

Refer to the directory demo/ASAP/ on the CD-ROM for additional information. 



10.6.2 The MP Protocol 

MP is an efficient IPC protocol to transfer mathematical data (see appendix 
A. 1.6). This example demonstrates a prototype of an MP module.^ Below, two 
Mu PAD kernels are started and exchange low-level data. 

^ Refer to http : //www . openmath . org/ 

^This modules uses ssh to launch applications like Singular. Thus ssh must be installed 
and correctly configured on your system. Ask your system administrator how to do this. 
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» module (mp) : 

» l:=mp: : Server ("poisson" ,6666) ; 

2906648 



» mp: : canWrite(l) ; 



TRUE 



» mp: :PutUint8Packet(l,42) : 

» mp: : PutReal64Packet(l, float (PI) ) : 
» mp: :eom(l) : 

» mp: : close(l) : 



» module (mp): 

» l:=mp: : Client ("poisson" ,6666) ; 

2979992 

» mp: :canRead(l) ; 

TRUE 

» if( mp::isEom(l) ) then mp::skip(l) end_if: 
» mp: :GetUint8Packet(l) ; 

42 

» mp: :GetReal64Packet(l) ; 

3.141592741 

» mp: : close(l) : 



This module is used to interact with the special purpose computer algebra 
system Singular. Refer to section 10.5.4 for a demonstration of the prototype of 
a user friendly Mu PAD interface to Singular. The module main source file mp . C 
lists the MP routines which are currently made available as Mu PAD functions: 

1 /////////////////////////////////////////////////////////////////////////////// 



2 // FILE : mp.C // 

3 // CONTENT: Module Interface to MP // 

4 // AUTHOR : Andreas Sorgatz (emdi@uni-paderborn.de) // 

5 // CREATED: 14. Dec. 1997 // 

6 // CHANGED: 25. Mar. 1998 // 

7 // RELEASE: MuPAD 1.4, MP-1.1.3 // 

8 // SYSTEMS: Solaris 2.5, Linux 2.0, HP-UX 9.x // 

9 // KNOWN BUGS: Speicherfreigabe von PARI und MP Apint sowie Strings // 



10 III! iiiiiiiii III mill iiiiiii n m mill II mill mill mill mu n mill mill 

11 MMG( attribute = static ) // the module must not be displaced 

12 

13 MMG( coption = "-IMP/include" ) 

14 MMG( Solaris: loption = "-LMP/lib/SUNMP -IMPT -IMP -Insl -Isocket" ) 

15 MMG( i386: loption = "-LMP/lib/LINUX -IMPT -IMP" ) 

16 

17 #include "mp.H" 

18 

19 // UTILITIES FOR SENDING/RECEIVING SPECIAL CONSTRUCTED OBJECTS 1111111111111111 

20 #include "mpBasic.C" 

21 #include "mpPoly.C" 

22 #include "mpIdeal.C" 

23 #include "mpOp.C" 

24 

25 // Contains function pointers to hemdle PARI numbers ////////////////////////// 

26 static MP_BigIntOps_t PariBigIntOps = 

27 { IMP.PutPariBigInt , 

28 IMP_GetPariBigInt, 
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29 IMP_PariBigIntToStr , 

30 IHP.PariBigIntAsciiSize 

31 }; 

32 

33 // Global HP environment will be initialized with the first use of openO ///// 

34 static MP_Env_pt HMPHenv = lULL; 

35 

36 /////////////////////////////////////////////////////////////////////////////// 

37 // FUHC UserOption 

38 // RESULT: Returns the User-Option mupad was started with 

39 /////////////////////////////////////////////////////////////////////////////// 

40 HFUICC UserOption, HCnop ) 

41 { HFreturn( MFstring( (char*)HUT_user_option() ) ); 

42 } HFEHD 

43 

44 /////////////////////////////////////////////////////////////////////////////// 

45 // COITROL OF HP EIVIROIHEIT AID LIIKS //////////////////////////////////////// 

46 /////////////////////////////////////////////////////////////////////////////// 

47 

48 /////////////////////////////////////////////////////////////////////////////// 

49 // FUIC : getEnv 

50 // RESULT: Returns the global HP environment 

51 /////////////////////////////////////////////////////////////////////////////// 

52 HFUIC( getEnv, HCnop ) 

53 { HFreturn( HFlongC (long) HHPHenv) ); 

54 } HFEHD 

55 /////////////////////////////////////////////////////////////////////////////// 

56 // FUHC open 

57 // PARAH : Refer to HP.OpenLink 

58 // RESULT: Opens a link and returns its handle 

59 /////////////////////////////////////////////////////////////////////////////// 

60 HFUHC( open, HCnop ) 

61 { static char* Argv[33] = { "mupad”, HULL }; 

62 static int Argc; 

63 HFnargsCheckRangeCl ,32) ; 

64 for( Argc = 1; Argc <= HVnargs; Argc++ ) { 

65 HFargCheck( Argc, DOH.STRIHG ); 

66 Argv[Argc] = HFstring( HFarg(Argc) ) ; 

67 } 

68 ArgvEArgc] = HULL; 

69 if ( HMPHenv == HULL ) { 

70 HMPHenv = HP_InitializeEnv( HULL ) ; 

71 HP_SetEnvBigIntFormat ( HHPHenv, ftPariBiglntOps , MP_GHP ); 

72 } 

73 HP_Link_pt Link = MP.OpenLinkC HHPHenv, Argc, Argv ); 

74 #ifdef MMPM.DEBUG 

75 HP_SetLinkOption( Link, HP_LIHK_LOG_MASK_OPT , HP_LOG_ALL_EVEHTS ); 

76 #endif 

77 HFreturnC HFlongC (long) Link) ); 

78 } HFEHD 

79 /////////////////////////////////////////////////////////////////////////////// 

80 HFUHCC close, HCnop ) 

81 { HFnargsCheck(l) ; 

82 MFargCheck(l,DOH_INT) ; 

83 HP.Link.pt Link = (HP_Link_pt) HFlongC MFarg(l) ); 

84 HP_CloseLink( Link ) ; 

85 HFreturnC MFcopy (HVnull) ) ; 

86 } HFEHD 

87 /////////////////////////////////////////////////////////////////////////////// 

88 HFUHCC eom, HCnop ) 

89 { HFnargsCheckCl) ; 

90 HFargCheck(l,DOH_INT) ; 

91 HP.Link.pt Link = (HP_Link.pt) HFlongC HFargCl) ); 

92 CHECK ( Link, HP.EndHsgReset (Link) ); 

93 HFreturnC MFcopyCHVnull) ); 

94 } HFEHD 
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95 /////////////////////////////////////////////////////////////////////////////// 

96 HFUHC( skip, MCnop ) 

97 { HFnargsCheck(l) ; 

98 HFargCheckCl ,D0H_IHT) ; 

99 MP_Link_pt Link = (HP_Link_pt) HFlongC HFarg(l) ); 

100 CHECK( Link, HP_SkipMsg(Link) ); 

101 MFreturnC HFcopy(HVnull) ) ; 

102 } HFEHD 

103 /////////////////////////////////////////////////////////////////////////////// 

104 HFUHC( isEom, MCnop ) 

105 { HFnargsCheck(l) ; 

106 MFargCheckCl ,D0M_IFT) ; 

107 HP_Link.pt Link = (HP_Link.pt) HFlong( HFarg(l) ); 

108 HFreturn( MFcopy(HUPBOOL(HP_TestEofHsg(Link))) ); 

109 } HFEHD 

no /////////////////////////////////////////////////////////////////////////////// 

111 HFUIC( canRead, HCnop ) 

112 { MFnargsCheck(l) ; 

113 HFargCheckCl ,D0M_IIT) ; 

114 HP_Link.pt Link = (MP.Link.pt) HFlongC HFargCl) ); 

115 ifC HP_GetLinkStatusCLink,HP_LinkReadyReading) == HP.TRUE ) 

116 HFreturnC HFcopyCMVtrue ) ) ; 

117 HFreturnC HFcopy (MVfalse) ); 

118 } HFEHD 

119 /////////////////////////////////////////////////////////////////////////////// 

120 MFUHCC canHrite, HCnop ) 

121 { HFnargsCheckCl) ; 

122 MFargCheckCl ,D0M_IHT) ; 

123 MP.Link.pt Link = (MP.Link.pt) HFlongC HFargCl) ); 

124 ifC HP_GetLinkStatus(Link,HP.LinkReadyHriting) == HP.TRUE ) 

125 MFreturnC HFcopyCMVtrue ) ) ; 

126 MFreturnC HFcopy (MVfalse) ); 

127 } HFEHD 

128 

129 /////////////////////////////////////////////////////////////////////////////// 

130 // SEHD AHD RECEIVE FUHCTIOHS FOR BASIC HP DATA TYPES (HO AHHOTATIOHS) //////// 

131 /////////////////////////////////////////////////////////////////////////////// 

132 

133 /////////////////////////////////////////////////////////////////////////////// 

134 HFUHCC PutBoole^LnPacket , HCnop ) 

135 { DO.HP.SEHDC MP.PutBooleanPacket , HP.Boolean.t , DOM.BOOL ,HUPB00L ); 

136 } HFEHD 

137 HFUHCC GetBoole€UiPacket , HCnop ) 

138 { DO.MP.RECVCHP.GetBooleanPacket , HP.Boolean.t, HP.Boolean.t, DOM.BOOL, HUPBOOL) ; 

139 } HFEHD 

140 /////////////////////////////////////////////////////////////////////////////// 

141 MFUHCC PutSintBPacket, MCnop ) 

142 { DO.HP.SEHDC HP.PutSintBPacket , HP.SintB.t, DOM.IHT, MFint ); 

143 } HFEHD 

144 HFUHCC GetSint8Packet, HCnop ) 

145 { DO.HP.RECVC HP.GetSintSPacket , HP.SintS.t, MP.SintS.t, DOM.IHT, MFint ); 

146 } HFEHD 

147 /////////////////////////////////////////////////////////////////////////////// 

148 MFUHCC PutUintBPacket , MCnop ) 

149 { DO.HP.SEHDC MP_PutUint8Packet , HP_Uint8_t, DOM.IHT, MFint ); 

150 } HFEHD 

151 HFUHCC GetUint8Packet , HCnop ) 

152 { DO.HP.RECVC HP.GetUintSPacket , HP.Uint8_t, HP.Uint8_t, DOM.IHT, MFint ); 

153 } HFEHD 

154 /////////////////////////////////////////////////////////////////////////////// 

155 HFUHCC PutSint32Packet , HCnop ) 

156 { DO.HP.SEHDC HP_PutSint32Packet , MP_Sint32_t, DOM.IHT, MFlong ); 

157 } HFEHD 

158 HFUHCC GetSint32Packet, MCnop ) 

159 { DO.HP.RECVC HP.GetSint32Packet , MP.Sint32.t, HP.Sint32.t, DOM.IHT, HFlong ); 

160 } HFEHD 
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161 

162 

163 
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168 

169 

170 

171 

172 

173 

174 

175 

176 

177 

178 

179 

180 
181 
182 

183 

184 

185 

186 

187 

188 
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224 
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226 



/////////////////////////////////////////////////////////////////////////////// 

HFUIC( PutUint32Packet , NCnop ) 

{ D0_MP_SEID( MP_PutUint32Packet , HP_Uint32_t, DOM^IHT, MFlong ); 

} HFEID 



MFUIC( GetUint32Packet , HCnop ) 

{ D0_HP_RECV(MP_GetUint32Packet, HP_Uint32_t ,HP_Uint32_t , D0M_IIT,MFuint32) ; 

} MFEND 

/////////////////////////////////////////////////////////////////////////////// 

HFUIC( PutReal32Packet , HCnop ) 

{ D0_HP_SEID( HP_PutReal32Packet , HP_Real32_t, DOH^FLOAT, MFfloat ); 

} HFEHD 

MFUNC( GetReal32Packet, HCnop ) 

{ D0_HP_RECV(HP_GetReal32Packet, HP_Real32_t ,HP_Real32_t , DOH_FLOAT,HFfloat) ; 

} HFEID 

/////////////////////////////////////////////////////////////////////////////// 

HFUHC( PutReal64Packet , HCnop ) 

{ DO_HP_SEND( HP_PutReal64Packet , HP_Real64_t, DOH.FLOAT, HFfloat ); 

} HFEID 

HFUICC GetReal64Packet , HCnop ) 

{ DO.HP.RECV (HP_GetReal64Packet , HP_Real64.t , HP_Real64_t , DOH.FLOAT , HFdouble ) ; 

} HFEID 

/////////////////////////////////////////////////////////////////////////////// 

HFUIC( PutStringPacket , HCnop ) 

{ DO_HP_SEID( HP.PutStringPacket , char*, DOH.STRIIG, HFstring ); 

} HFEID 



HFUIC( GetStringPacket , HCnop ) 

{ DO_HP_RECV( HP_GetStringPacket , char*, char*, DOH_STRIIG, HFstringFree ); 

} HFEID 

/////////////////////////////////////////////////////////////////////////////// 
HFUIC( PutIdentifierPacket , HCnop ) 

{ DO.HP_SEID( HP.PutStringPacket, char*, DOH.IDEIT, HFident ); 

} HFEID 

HFUIC( GetIdentifierPacket , HCnop ) 

{ DO_HP_RECV( HP.GetStringPacket , char*, char*, DOH.IDEIT, HFidentFree ); 

} HFEID 

/////////////////////////////////////////////////////////////////////////////// 
HFUIC( PutApIntPacket , HCnop ) 

{ DO_HP_SEID( HP.PutApIntPacket, GEI, DOH_APH, HFpari ); 

} HFEID 

HFUICC GetApIntPacket, HCnop ) 

{ DO_HP_RECV( HP.GetApIntPacket, GEI, void*, DOH.APH, HFpari ); 

} HFEID 



/////////////////////////////////////////////////////////////////////////////// 
// SEID FUICTIOIS FOR HP DATA ///////////////////////////////////////////////// 
/////////////////////////////////////////////////////////////////////////////// 



/////////////////////////////////////////////////////////////////////////////// 

HFUICC write, HCnop ) 

{ HFnargsCheckC2) ; HFargCheckCl ,DOH_IIT) ; 

HP_Link_pt Link = CHP_Link_pt) HFlongC HFargCl) ); 

HTcell Arg = HFargC2) ; 

switchC HFdomCArg) ) { 
case DOH.APH: 
case DOH_IIT: 
case DOH.COHPLEX: 
case DOH.FLOAT: 
case DOH_RAT : 

wlumberC Link, Arg ); 
break ; 

case DOH.IDEIT: 

wIdentC Link, Arg ); 
break ; 

case DOM.STRIHG; 

wStringC Link, Arg ); 
break ; 
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227 case D0H_EXPR: 

228 if( HFisExpr(Arg, "Ideal") ) wIdeaK Link, Arg ); 

229 if( HFisExpr(Arg, "Std") ) wStd( Link, Arg ); 

230 if( MFisExprCArg, "StdFglra") ) wStdFglmC Link, Arg ); 

231 bre 2 ik; 

232 case D0H_P0LY: 

233 wPoly( Link, Arg ); 

234 breaik ; 

235 default : 

236 HFerror( "Fatal: This data type is not supported yet" ); 

237 } 

238 HP_EndHsgReset( Link ) ; 

239 MFreturnC HFcopy(HVnull) ) ; 

240 } HFEHD 

241 

242 /////////////////////////////////////////////////////////////////////////////// 

243 // RECEIVE FUHCTIOIS FOR MP DATA ////////////////////////////////////////////// 

244 /////////////////////////////////////////////////////////////////////////////// 

245 

246 /////////////////////////////////////////////////////////////////////////////// 

247 MTcell cTree2Any( MPT_Tree_pt Tree ) 

248 { if( Tree == MULL ) return ( HFcopy (HVnull) ); 

249 HPT_Hode_pt Bode = Tree->node; 

250 switchC Hode->type ) { 

251 case MP_Sint8Type : returnC HFlong( (long) HP_SIIT8_T (Iode->nvalue) ) ); 

252 case HP_Uint8Type: returnC HFlongC (long) HP_UIIT32_T(Iode->nvalue)) ); 

253 case MP_Sint32Type : returnC HFlong(dong) HP_SIIT32_T(Iode“>nvalue) ) ); 

254 case MP_Uint32Type: returnC HFlongC (long) HP_UIHT32_T(Bode->nvalue)) ); 

255 case HP_Real32Type : returnC HFdouble ((double )MP_REAL64_T(Iode->nvalue)) ) ; 

256 case HP_Real64Type : returnC HFdouble ( (double) HP_REAL64_T(Bode->nvalue) )) ; 

257 case MP.ApIntType: returnC HFpari((GEH) HP_APIBT_T (Iode->nvalue) ) ) ; 

258 case HP_StringType : returnC HFstringC HP_STRIIG_T (Iode->nvalue) ) ); 

259 case MP_Identif ierType : returnC MFident ( HP_STRIIG_T (Iode->nvalue) ) ); 

260 case HP.BooleanType : returnC HUPBOOL ( HP.BOOLEAH.T(Hode->nvalue) ) ); 

261 case HP.CommonOperatorType : { ////////////////////////////////////////////// 

262 MPT_Tree_pt TypeSpec = HPT_GetProtoTypespec( lode ) ; 

263 { // Polynomials /////////////////////////////////////////////////////////// 

264 HP_Sint32_t Char; 

265 MPT_Tree_pt Vars ; 

266 HP_Common_t Order; 

267 ifC HPT.IsDDPTreeCTree, ftChar, ftVars, ftOrder) ) { 

268 if(Char<0) MFerror ( "Fatal : Characteristic of polynomials is negative"); 

269 MTcell Po = cTree2Poly (Tree->args , Iode->numchild, Char , Vars , Order) ; 

270 HPT.DeleteTreeC Vars ) ; 

271 returnC Po ); 

272 } 

273 } 

274 { // Ideals //////////////////////////////////////////////////////////////// 

275 MP_Sint32_t Char; 

276 HPT.Tree.pt Vars ; 

277 HP.Common.t Order; 

278 ifC MPT.IsIdealTreeCTree, ftChar, kVais, ftOrder) ) { 

279 if(Char<0) HFerror ("Fated : Characteristic of polynomieds is negative"); 

280 MTcell Id = cTree2Ideal(Tree->args , Iode->numchild , Char , Vars , Order ) ; 

281 HPT.DeleteTreeC Vars ); 

282 returnC Id ) ; 

283 } 

284 } 

285 { // Prototypen entfernen (Tree umstrukturieren) da sie im :folgenden nicht / 

286 // beruecksichtigt nerden koennen oder sollen. Dies vereinfacht das Ein- / 

287 // lesen deutlich. 

288 ifC TypeSpec != HULL ftft HPT. IsTrueProtoTypeSpec (TypeSpec) ) { 

289 MPT.UntypespecTreeC Tree ) ; 

290 returnC cTree2Any(Tree) ) ; 

291 } 

292 



} 
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293 { // Rationals ///////////////////////////////////////////////////////////// 

294 if( CheckHode(Hode ,HP_BasicDict , (MPT_Arg_t) MP_CopBasicDiv) ftft 

295 TypeSpec != HULL ftft 

296 CheckIode( TypeSpec-*>node , HP_ConunonMetaType , MP_IumberDict , 

297 (HPT_Arg_t) HP.Cmtlumber Integer) ) { 

298 HTcell tmp = cTree2Any( (HPT_Tree_pt) Tree->args[0] ) ; 

299 HTcell hip = cTree2Any ( (HPT_Tree_pt) Tree->args[l] ) ; 

300 returnC MFrat(tmp,hlp) ); 

301 } 

302 } 

303 { // Complex /////////////////////////////////////////////////////////////// 

304 if( CheckNodeCHode ,HP_BasicDict , (MPT_Arg_t) HP.CopBasicComplex) ) { 

305 return( HFcomplex(cTree2Any( (HPT_Tree_pt) Tree->args[0] ) , 

306 cTree2Any((HPT_Tree_pt) Tree->args[l] ) ) ); 

307 } 

308 } 

309 { // List ////////////////////////////////////////////////////////////////// 

310 if( CheckHodedode ,HP_BasicDict , (MPT_Arg_t) HP_CopBasicList) ) { 

311 return( cTree2List (Tree->args , Hode->numchild) ); 

312 } 

313 } 

314 { // Division ////////////////////////////////////////////////////////////// 

315 if( CheckHodedode ,HP-BasicDict , (MPT.Arg^t) HP.CopBasicDiv) ) { 

316 if( Hode->numchild != 2 ) HFerror( "Bad division" ); 

317 HTcell tl = cTree2Any( (HPT_Tree.pt) Tree->args[0] ) ; 

318 HTcell t2 = cTree2Any( (HPT_Tree_pt ) Tree->args[l] ) ; 

319 return( HFnewExprO, HFident ("_mult" ), tl, 

320 HFnewExprO, HFident (".power") , t2, HFcopy (HVone.) ) ) ); 

321 } 

322 } 

323 HFerror( "Fatal: Unknown common operator or dictionary: cTree2AnyO" ); 

324 } ////////////////////////////////////////////////////////////////////////// 

325 default : 

326 HFerror( "Fatal: Unknown node type: cTree2AnyO" ); 

327 } 

328 } 

329 

330 /////////////////////////////////////////////////////////////////////////////// 

331 HFUIC( read, HCnop ) 

332 { HFnargsCheck(l) ; 

333 HFargCheck(l,DOH_IHT) ; 

334 

335 HP_Link.pt Link = (HP_Link.pt) HFlong( HFarg(l) ); 

336 if ( HP.TestEofHsg(Link) ) HP_SkipHsg( Link ) ; 

337 

338 HPT_Tree.pt Tree; 

339 CHECK ( Link, HPT_GetTree(Link, ftTree) ); 

340 HTcell Result = cTree2Any( Tree ) ; 

341 HPT_DeleteTree( Tree ) ; 

342 HFreturn( Result ) ; 

343 } HFEHD 



Refer to the directory demo/MP/ on the CD-ROM for additional information. 

The dynamic module MP was implemented in cooperation with Olaf Bachmann 
and Hans Schdnemann from the Zentrum fiir Computeralgebra^ Universitat 
Kaiserslautern, Germany. 

Many thanks to Simon Gray from the Department of Mathematics and Com- 
puter Science at the Kent State University, Kent, USA for his support concern- 
ing MP. 
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10.6.3 MuPAD Macro Parallelism 

The PVM library supports to use a collection of heterogeneous computers as a 
coherent and flexible concurrent computational resource (see appendix A. 1.8). 

The module net demonstrates a prototype of the macro parallelism in MuPAD 
which implementation is based on the PVM library.® 

For a detailed description of the macro parallelism and the usage of the module 
net refer to the article News about Macro Parallelism in MuPAD I .4 [5] which 
is also available on the CD-ROM as demo/NET/doc/makrop.ps. Also refer to 
the manual [24] and the technical report [21]. 



» module (net): 


Module *net* for macro parallelism was loaded successfully. 


Start with NETCONF:=["host"=#(cluster) , 


. . .] : net : :master() 


» NETC0NF:= [ "wiwianka"=2 , "gauss"=l, 
» net: : master () : 


"horner"=l ] : 


» topologyO; 

c 


// get number of clusters 


» net : : ismasterO ; 


// is this the master? 


TRUE 




» topology(Cluster) ; 

1 


// get the local cluster-id 


» writequeueC'work" ,3,hold( 


// ask #3 if it is master 


writepipe(YesIam, 1, net :: ismasterO))) ; // it writes to pipe Yeslam I 


» readpipe(YesIam,3,Block) ; 


// read answer from the pipe 


FALSE 




» global(a,42) : 


// set a global variable 


» global(a,global(a)+l) , global(a); 


// increment global variable 


42, 43 




» net : : shutdownO : 





Special to this example is, that the module net uses signals (SIGALRM). The 
main source file of this modules is listed below: 

1 /////////////////////////////////////////////////////////////////////////////// 

2 //= MODULE : net.C — Module interface code of the macro parallelism prototype 

3 //= AUTHOR : Andreas Sorgatz (andiQmupad.de) 

4 //= Manfred Radimersky (maradimOmupad.de) 

5 //= Torsten Metzner (tomOmupad.de) 

27 /////////////////////////////////////////////////////////////////////////////// 

29 #include "net.H" 

30 

31 /////////////////////////////////////////////////////////////////////////////// 

32 // Configuration: linking of network libraries 

®This modules uses ssh to launch the MuPAD clusters. Thus ssh must be installed and 
correctly configured on your system. Ask your system administrator how to do this. 
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MMG( loption = "-lpvm3" ) // PVM library (PIC!) 

HMG( Solaris: loption = "-Isocket -Insl" ) // Solaris net libraries 

/////////////////////////////////////////////////////////////////////////////// 
// Global variable to save the local module domain from garbage collection 
HTcell MAPVdom; // local module domain 



/////////////////////////////////////////////////////////////////////////////// 

//= FUNC: initmod 

//= IHFO: This function is called automatically when loading this module by use 
//= of ’moduleO’. Depending on HAPisMaster / HAPisSlave it starts up the 
//= kernel as master respectively slave of the macro parallelism or only 
//= informs the user how to do this later. 



/////////////////////////////////////////////////////////////////////////////// 



HFUIC( initmod, HCstatic ) 

{ static int WasCalledBefore = 0; 
HAPVdom = HVdomain; 

MFglobaK ftHAPVdom ) ; 



// module must not be displaced 
// status of this module 
// save local module domain I ! ! 
// no garbage collection III!!! 



if( WasCalledBefore ) { 

HFputs( "Hesg. : Module was initialized before - skipping ’initmod’" ); 
HFreturn( HFcopy (HVnull) ); 

} 

HAPVinitO; // init. for standalone kernel 

HAPsetTransHode("MCODE") ; // default mode 



// Remove this line in dirtibuted versions ////////////////////////////////// 
HAPenterDebugHodeO ; // only if user configured 

// Export the documented user functions of the macro paralellism in ciny case 
HFfree (HFeval(HF("sysassign (global , net::global ):" 

"sysassign(globale , net::globale ):" 

"sysassign(readqueue , net : : readqueue ):" 

"sysassign(readpipe , net : : readpipe ):" 
"sysassign(writequeue , net: :writequeue) :" 

"sysassign(writepipe , net : : writepipe ):" 

"sysassign(topology , net :: topology ):" 

) ) ); 

MFprintf ("Module ’net’ for macro parallelism was loaded successfully . \n") ; 

MAPTerror errni; 
if( MAPprefMasterO ) { 

MFprintf ("Starting network using configuration lETCOIF. . .\n\n") ; 
errni = MAPinitMaster () ; 
if( !errni . isokO ) { 

MFputs ( MAPerrstrg(errni) ) ; 
errni = MAPshutdownO ; 

} 

} else if( MAPprefSlaveO ) { 

MFprintf ("Starting slave of macro parallelism. . .\n\n") ; 
errni = MAPinitSlaveO ; 
if( lerrni.isokO ) { 

MFputs ( MAPerrstrg(errni) ) ; 
errni = MAPterminateO ; 

} 

} else { 

MFputs("Start with lETCOIF : = [\"host\"=#(cluster) ,...] : net : ;master( )\n") ; 

} 



WasCalledBefore = 1 ; 

if( lerrni.isokO ) MFerror( MAPerrstrg(errni) ); 

MFreturn( MFcopy (MVnull) ) ; 

} MFEID 

/////////////////////////////////////////////////////////////////////////////// 
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106 //= FUIC: ln^uster 

107 //= IIFO: Start the kernel as the master of the macro parallelism. 

108 /////////////////////////////////////////////////////////////////////////////// 

109 MFUIC( master, HCnop ) 

110 { if( MAPisSlaveO || HAPprefSlaveO ) 

111 MFerror( "Ceumot be started on slave" ) ; 

112 NAPcheckIsDownO ; 

113 HAPTerror errni = HAPinitHasterO ; 

114 if( lerrni.isokO ) HFerror( HAPerrstrg(errni) ); 

115 HFreturn( MFcopy(MVtrue) ) ; 

116 } HFEID 

118 /////////////////////////////////////////////////////////////////////////////// 

120 //= FUIC: ismaster 

121 //= IIFO: Returns TRUE if the current kernel is the m 2 ister of macro parallelism 

122 /////////////////////////////////////////////////////////////////////////////// 

123 MFUICC ismaster, HCnop ) 

124 { HAPcatchEventsO ; 

125 HFreturnC HFbooK! MAPisSlaveO) ); 

126 } HFEID 

128 /////////////////////////////////////////////////////////////////////////////// 

130 //= FUIC: shutdown 

131 //= IIFO: Shutdown the macro parallelism. 

132 /////////////////////////////////////////////////////////////////////////////// 

133 HFUIC( shutdown, HCnop ) 

134 { HAPTerror errni; 

135 if( HAPisUpO ) HAPshutdownO ; 

136 HFreturn( HFbool(errni.getcode()==HAPD_OK) ); 

137 } HFEID 

139 /////////////////////////////////////////////////////////////////////////////// 

141 //= FUIC: halt 

142 II- IIFO: Halts the macro parallelism completely. 

143 /////////////////////////////////////////////////////////////////////////////// 

144 HFUIC( halt, HCnop ) 

145 { HAPhaltO; 

146 HFreturn( MFcopy(MVfalse) ) ; 

147 } HFEID 

149 /////////////////////////////////////////////////////////////////////////////// 

151 //= FUIC: readqueue 

152 II- IIFO: Reads from a local queue. Reading may be ’Block ’ed. 

153 /////////////////////////////////////////////////////////////////////////////// 

154 HFUICC readqueue, HCnop ) 

155 { HFnargsCheckRanged , 2); 

156 if((MVnargs == 2) Aft !MFisIdent(HFarg(2) , "Block")) { 

157 MFerrorC'Invalid Option") ; 

158 } 

159 HTcell Value; 

160 HAPTerror errni = HAPreadQ( HFarg(l), ftValue, HVnargs==2 ); 

161 if( ! errni .isokO ) MFerror( HAPerrstrg(errni) ); 

162 HFreturn( Value ) ; 

163 } HFEID 

165 /////////////////////////////////////////////////////////////////////////////// 

167 //= FUIC: readpipe 

168 //= IIFO: Reads from a local pipe. 

169 /////////////////////////////////////////////////////////////////////////////// 

170 HFUIC( readpipe, HCnop ) 

171 { HFnargsCheckRange(2, 3); 

172 MFargCheck(2, HCnumber) ; 

173 if((HVnargs == 3) Aft !HFisIdent(HFarg(3) , "Block")) { 

174 MFerror ("Third argument , must be option ‘Block’!"); 

175 } 

176 HTcell Value; 

177 HAPTerror errni = MAPreadPC HFarg(l), HFarg(2) , AValue, HVnargs==3 ); 

178 if( !errni . isokO ) MFerror( HAPerrstrg(errni) ); 

179 HFreturn( Value ); 

180 } HFEID 

182 /////////////////////////////////////////////////////////////////////////////// 
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II- FUIC: ffritequeue 

//= IIFO: Writes into a local or remote queue. 
/////////////////////////////////////////////////////////////////////////////// 
MFUIC( uritequeue, NCnop ) 

{ MFnargsCheck(3) ; 

MFar gChe ck ( 2 , HCnumbe r ) ; 

HAPTerror errni = MAPwriteQ( MFarg(l), MFarg(2) , HFarg(3) ); 
if( ! errni . isokO ) HFerror( HAPerrstrg(ermi) ); 

HFreturn(HFcopy(MVnull) ) ; 

} HFEID 

/////////////////////////////////////////////////////////////////////////////// 

II- FUIC: writepipe 

II- IIFO: Writes into a local or remote pipe. 
/////////////////////////////////////////////////////////////////////////////// 
HFUIC( writepipe, HCnop ) 

{ MFnargsCheck(3) ; 

HFargCheck(2, HCnumber) ; 

HAPTerror errni = HAPwriteP( HFarg(l), HFarg(2) , MFarg(3) ); 
if( ! errni . isokO ) MFerror( HAPerrstrg(errni) ); 

HFreturn(HFcopy(HVnull)) ; 

} HFEID 

/////////////////////////////////////////////////////////////////////////////// 

//= FUIC: topology 

//= IIFO: Returns information about the topology of the macro parallelism. 
/////////////////////////////////////////////////////////////////////////////// 
HFUIC( topology, HCnop ) 

{ HFnargsCheckRange(0 , 1); 
long Res; 

if( HVnargs == 1 ) { 

if( HFisIdent(HFarg(l) , "Cluster") ) { // get my cluster number 

Res = HAPclusterlumO ; 

} else { // get micro parallelism info 

HFargCheckd , HCnumber) ; 
long lura = HFlong(HFargd) ) ; 

if( (lum < 0) I I ! (Res=HAPtopoHicro((HAPT: :cluster_t) lum)) ) 

HFerrorC "Invalid cluster" ) ; 

} 

} else { // get macro parallelism info 

Res = HAPtopoHacroO ; // get number of clusters 

} 

HFreturn( MFlong(Res) ) ; 

} HFEID 

/////////////////////////////////////////////////////////////////////////////// 

//= FUIC: global 

//= IIFO: Reads and writes global (network) variables, hold first argument 
/////////////////////////////////////////////////////////////////////////////// 
HFUIC( global, HChold ) 

{ HFnargsCheckRanged , 2); 

HFargCheckd, DOH.IDEIT) ; 

HTcell Value; 

HAPTerror errni; 

if( HVnargs == 1) { 

errni = HAPreadGlobaK HFarg(l) , ftValue ); 

if( ! errni . isokO ) HFerrorC HAPerrstrg(errni) ); 

HFreturnC Value ) ; 

} else { 

errni = HAPwriteGlobalC HFarg(l), HFarg(2) , ftValue ); 
if( ierrni . isokO ) HFerrorC HAPerrstrgCerrni) ); 

HFreturnC Value ) ; 

} 

} HFEID 

/////////////////////////////////////////////////////////////////////////////// 

//= FUIC: globale 

//= IIFO: Reads and writes global (network) variables, eval first argument 

/////////////////////////////////////////////////////////////////////////////// 
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259 MFUICC globale, HChold ) 

260 { HFnargsCheckRange(2, 3); 

262 MTcell lewLevel, OldLevel; 

263 MTcell lame, Value; 

264 HAPTerror errni ; 

265 

266 HewLevel = MFexecC HFcopy(MFarg(l) ) ); 

267 if( IMFisIntegerdewLevel) ) { 

268 MFerrorC'First argument must evaluate to integer!"); 

269 } 

271 OldLevel = HFgetVar ( "LEVEL" ) ; 

272 HFsetVarC "LEVEL", lewLevel ); 

273 Name = MFexecC MFcopy(MFarg(2) ) ); 

274 MFsetVarC "LEVEL", OldLevel ); 

275 if( IMFisIdent(Iame) ) { 

276 MFerrorC'First argument must evaluate to identifier!"); 

277 } 

279 if( MVnargs == 2 ) { 

280 errni = MAPreadGlob 2 d ( Name, ftValue ); 

281 if( ! errni . isokO ) MFerrorC MAPerrstrg(errni) ); 

282 MFreturnC Value ); 

283 } else { 

284 errni = MAPwriteGlobalC Name, MFarg(3) , ftValue ); 

285 if( ! errni . isokO ) MFerrorC MAPerrstrgCerrni) ); 

286 MFreturnC Value ) ; 

287 } 

288 } MFEND 

290 /////////////////////////////////////////////////////////////////////////////// 

292 //= FUNC: mprint 

293 //= INFO: print an expression on the master 

294 /////////////////////////////////////////////////////////////////////////////// 

295 MFUNCC mprint, MCnop ) 

296 { MFnargsCheckCl) ; 

297 MAPTerror errni = MAPmprintC MFargCl) ); 

298 ifC !errni . isokC) ) MFerrorC MAPerrstrgCerrni) ); 

299 MFreturnCMFcopyCMVnulD) ; 

300 } MFEND 

302 /////////////////////////////////////////////////////////////////////////////// 

304 //= FUNC: gfree 

305 //= INFO: locates non-group-members in the network 

306 /////////////////////////////////////////////////////////////////////////////// 

307 MFUNCC gfree, MCnop ) 

308 { MFnargsCheckCl) ; 

309 MFargCheckC 1, D0M_B00L ); 

310 MTcell Result; 

311 MAPTerror errni = MAPgfreeC MFboolC MFargCl) ), ftResult ); 

312 ifC ! errni . isokC) ) MFerrorC MAPerrstrgCerrni) ); 

313 MFreturnCResult) ; 

314 } MFEND 

316 /////////////////////////////////////////////////////////////////////////////// 

318 //= FUNC: gmasterinit 

319 //= INFO: initializes a work group master 

320 /////////////////////////////////////////////////////////////////////////////// 

321 MFUNCC gmasterinit, MCnop ) 

322 { MFnargsCheckCO) ; 

323 MAPTerror errni = MAPgmasterinitC) ; 

324 ifC !errni . isokC) ) MFerrorC MAPerrstrgCerrni) ); 

325 MFreturnCMFcopyCMVnulD); 

326 }• HFEHD 

328 /////////////////////////////////////////////////////////////////////////////// 

330 //= FUNC: gmasterquit 

331 //= INFO: deinitializes a work group master 

332 /////////////////////////////////////////////////////////////////////////////// 

333 MFUNCC gmasterquit, MCnop ) 

334 { MFnargsCheckCO) ; 

335 MAPTerror errni = MAPgmasterquitC) ; 
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336 if( lerrni . isokO ) MFerrorC HAPerrstrg(errni) ); 

337 MFreturn(HFcopy(HVnull)) ; 

338 } MFEID 

340 /////////////////////////////////////////////////////////////////////////////// 

342 //= FUIC: gslaveinit 

343 //= IIFO: initializes a work group slave 

344 /////////////////////////////////////////////////////////////////////////////// 

345 HFUICC gslaveinit, HCnop ) 

346 { HFnargsCheck(l) ; 

347 MFargCheckCl, HCnumber) ; 

348 HAPTerror errni = HAPgslaveinit( HFlong(MFargd) )-l ); 

349 if( lerrni.isokO ) HFerrorC MAPerrstrg(errni) ); 

350 HFreturn(HFcopy(HVnull)) ; 

351 } HFEID 

353 /////////////////////////////////////////////////////////////////////////////// 

355 //= FUIC: gslavequit 

356 //= IIFO: deinitializes a work group slave 

357 /////////////////////////////////////////////////////////////////////////////// 

358 HFUICC gslavequit, HCnop ) 

359 { MFnargsCheck(O) ; 

360 HAPTerror errni = HAPgslavequitO ; 

361 if( ! errni. isokO ) HFerror( HAPerrstrg(errni) ); 

362 HFreturn(HFcopy(HVnull)) ; 

363 } HFEID 

365 /////////////////////////////////////////////////////////////////////////////// 

367 //= FUIC: gcluster 

368 II- IIFO: returns group cluster type (0 = none, 1 = gmaster, 2 = glsave) 

369 /////////////////////////////////////////////////////////////////////////////// 

370 HFUIC( gcluster, HCnop ) 

371 { HFnargsCheck(O) ; 

372 HFreturn (HFlongCHAPgcluster ( ) ) ) ; 

373 } HFEID 

375 /////////////////////////////////////////////////////////////////////////////// 

377 II- FUIC: gmaster 

378 II- IIFO: returns group master of group member (0 if not group member) 

379 /////////////////////////////////////////////////////////////////////////////// 

380 HFUIC( gmaster, HCnop ) 

381 { HFnargsCheck(O) ; 

382 HFreturn (HFlong(HAPgmaster() ) ) ; 

383 } HFEID 

385 /////////////////////////////////////////////////////////////////////////////// 

387 //= FUIC: gjob 

388 II- IIFO: creates a new group job 

389 /////////////////////////////////////////////////////////////////////////////// 

390 HFUIC( gjob, HCnop ) 

391 { HTcell Handle; 

392 HFnargsCheck(2) ; 

393 HFargCheckCl , HCnumber); 

394 HAPTerror errni = HAPgjobC HFlong(HFarg(l))-l , HFarg(2) , ftHemdle ); 

395 if( lerrni.isokO ) HFerrorC HAPerrstrg(errni) ); 

396 HFreturn ( Handle ) ; 

397 } HFEID 

399 /////////////////////////////////////////////////////////////////////////////// 

401 II- FUIC: gstatus 

402 II- IIFO: get status of group job 

403 /////////////////////////////////////////////////////////////////////////////// 

404 HFUIC( gstatus, HCnop ) 

405 { HTcell Status; 

406 HFnargsCheck(2) ; 

407 HFargCheckCl, HCnumber); 

408 HFargCheck(2, HCnumber); 

409 HAPTerror errni = HAPgstatusC HFlong(HFargCl) )-l , HFarg(2) , ftStatus ); 

410 if( lerrni.isokO ) HFerrorC HAPerrstrgCerrni) ); 

411 HFreturnC Status ) ; 

412 } HFEHD 

414 /////////////////////////////////////////////////////////////////////////////// 
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416 //= FUHC: gresult 

417 //= IHFO: get result of group job 

418 /////////////////////////////////////////////////////////////////////////////// 

419 HFUHCC gresult, HCnop ) 

420 { HTcell Result; 

421 HFnargsCheck(2) ; 

422 NFargCheckd , HCnumber) ; 

423 MFargCheck(2 , HCnumber); 

424 HAPTerror errni = HAPgresult( MFlong(HFarg(l) )-l , HFarg(2) , ftResult ); 

425 if( ! errni. isokO ) HFerror( HAPerrstrg(errni) ); 

426 HFreturnC Result ) ; 

427 } HFEND 

429 /////////////////////////////////////////////////////////////////////////////// 

431 //= FUHC: gprocess 

432 //= IHFO: force processing of new group job uhile the old one is waiting 

433 /////////////////////////////////////////////////////////////////////////////// 

434 MFUHCC gprocess, HCnop ) 

435 { HFnargsCheck(O) ; 

436 HAPTerror errni = HAPgprocessO ; 

437 if( !errni . isokO ) HFerror( HAPerrstrg(errni) ); 

438 HFreturn( HFcopy(HVnull) ); 

439 } HFEHD 

441 /////////////////////////////////////////////////////////////////////////////// 

443 //= FUHC: pref 

444 //= IHFO: Set preferences of the macro parallelism of module ’net’ 

445 /////////////////////////////////////////////////////////////////////////////// 

446 HFUHC( pref, HChold ) 

447 { HFnargsCheckC 1 ); 

448 HAPcatchEventsO ; 

450 if( HFisIdent(HFargd)) ) { //////////////////////////// Get an option 

451 if( HFisIdent(HFargd) ,"LogError") ) { // LogError 

452 HFreturn( HFbool(HAPgetReport() ) ); 

453 

454 } else if( HFisIdent(HFargd) ,”GarbCol") ) { // GarbCol 

455 HFreturn( HFbool(HAPgetGarbColO) ); 

456 

457 } else if( HFisIdent(HFargd) ,"ComType") ) { // ComType 

458 HFreturnC HFstring(HAPgetTransHode() ) ); 

459 

460 } else HFerrorC "Invalid Option" ) ; 

461 } 

463 if( !HFisExpr(HFarg(l) , ".equal") ) /////////////////////////// Set an option 

464 HFerrorC "Equation ’Option [=Value] ’ expected" ); 

465 

466 HTcell Option = HFopC HFargCl), 1 ); 

467 HTcell Value = HFopC HFargCl), 2 ); 

468 ifC HFisIdentCOption, "LogError") ) { // LogError 

469 

470 if C HFisTrueC Value) | | HFisFalseCValue) ) 

471 HAPsetReportC HFboolC Value) ) ; 

472 else 

473 HFerrorC "Invalid value for option ’LogError’" ); 

474 

475 } else ifC HFisIdentCOption ,"GcirbCol") ) { // GarbCol 

476 

477 ifC HFisTrueC Value) || HFisFalseCValue) ) 

478 HAPsetGarbColC HFboolCValue) ); 

479 else 

480 HFerrorC "Invalid value for option ’GarbCol’" ); 

481 

482 } else ifC HFisIdent COption , "ComType") ) { // ComType 

483 ifC HAPisUpC) ) { 

484 HFerrorC "Hust be configured before network is started" ) ; 

485 } 

486 ifC HFisStringCValue) ) { 

487 ifC IHAPsetTreuisHodeCHFstringCValue) ) ) { 
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488 

489 

490 

491 

492 

493 

494 

495 

496 

497 

498 

499 

500 

501 

502 
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504 
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509 

510 

511 
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514 

515 

516 

518 

519 

520 

521 
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523 

524 
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528 

529 

530 

531 
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535 
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537 

538 

539 

540 

541 

542 

543 

544 

545 

546 

547 

548 

549 

550 

551 

552 

554 

555 

556 

557 

558 



MFerror( "Invalid ’ComType’" ); 

} 

} else 

MFerrorC "String expected for option ’ComType’" ); 

} else MFerror( "Invalid Option" ) ; 

MFreturn( HFcopy (MVnull) ) ; 

} HFEHD 

/////////////////////////////////////////////////////////////////////////////// 

/////////////////////////////////////////////////////////////////////////////// 

// FUHC: HAPenterDebugHode 

// INFO: Returns information about the topology of the macro parallelism. 
/////////////////////////////////////////////////////////////////////////////// 
int HAPenterDebugHode 0 
{ int error = 0; 

if( HAPisSlaveO ) { // for Xll clients (xxgdb) 

HTcell netdisplay = HFgetVar ("NETDISPLAY") ; 
if( !HFequal (netdisplay, HCnull) ) { 
static char display [512] ; 

sprintf( display, "DISPLAY=*/.s" , HFstring(netdisplay) ); 

HFfreeC netdisplay ); 
error = putenv (display) ; 

HFprintf( "Display on: */,s\n" , getenv("DISPLAY") ); 

} 

} 

HTcell netsrcpath = HFgetVar ("NETSRCPATH") ; // for module source net.C 

if( !HFequal (netsrcpath, HCnull) ) { 

if( chdir(HFstring(netsrcpath)) == -1 ) error = 1; 
else { 

HFprintf( "Debug path: */,s\n" , HFstring(netsrcpath) ); 

} 

} 

return( ! error ); 



/////////////////////////////////////////////////////////////////////////////// 

/////////////////////////////////////////////////////////////////////////////// 

//= PROC: map 

//= INFO: apply a function to each element of a given list and distribute 
//= the function evaluations over the macro parallel network 

/////////////////////////////////////////////////////////////////////////////// 

HPR0C( map = "proc(l,f) 

local n, i, result, missing, res, resqu; 
begin 

resqu : =expr2text (genident (\"result\" ) ) ; 
userinfo(20 ,\"Using queue \". resqu. \" for results\") ; 
n :=nops(l) ; 
result := [FAIL $n] ; 

userinfo(20, \"Parallel map on list of length \" . expr2text (n) ) ; 
userinfo(20, \"List is \" . expr2text (1) ) ; 
for i from 1 to min(n ,topology()-l) do 

userinfodO, \"Task \" . expr2text(i) . \" goes to cluster \" . expr2text (i+1) ) ; 
writequeue(\"work\" , i+1, hold(writequeue) ( resqu, 1, 

[hold(fp :: apply) (f , l[i] , args(3. .args(O))) , i, i+1])) 
end.for ; 
missing:=i-l ; 

userinfo(20, expr2text (missing) . \" results are waited for\") ; 
repeat 

res :=readqueue (resqu , Block); 

userinfodO, \"Cluster \" . expr2text (op(res ,3) ) . \" has finished task 
number \" . expr2text (op(res , 2) ) ) ; 
userinfo(20, \"Result is \" . expr2text (op(res , 1) ) ) ; 
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559 result [op(res ,2)] :=op(res,l) ; 

560 if i<=n then 

561 userinfoClO, \"Task \" .expr2text(i) A" goes to cluster \". 

562 expr2text(op(res,3)>) ; 

563 eritequeue(\"work\" , op(res»3), hold(writequeue) ( resqu, 1, 

564 [hold(fp: rapply) (f ,l[i3 » args(3. .args(O))) , i, opCres ,3)] ) ) ; 

565 i:=i+l 

566 else 

567 missing : =missing-l ; 

568 userinfo(20, \"Io more tasks to distributeX") ; 

569 user info (20 » expr2text (missing) A" results are still waited for\") 

570 end.if 

571 until missing^O end.repeat; 

572 result 

573 end_proc" 

574 ) 

576 /////////////////////////////////////////////////////////////////////////////// 

578 //= PROC: initlock 

579 //= IIFO: init global lock variable 

580 /////////////////////////////////////////////////////////////////////////////// 

581 HPR0C( initlock = "proc( lid ) 

582 begin globale( 1, lid, FALSE ) 

583 end_proc" 

584 ) 

586 /////////////////////////////////////////////////////////////////////////////// 

588 //= PROC: spinlock 

589 //= IIFO: set global lock variable, blocking 

590 /////////////////////////////////////////////////////////////////////////////// 

591 MPR0C( spinlock = •'proc( lid ) 

592 begin while globale( 1, lid, TRUE ) do end_while; 

593 end_proc" 

594 ) 

596 /////////////////////////////////////////////////////////////////////////////// 

598 //= PROC: setlock 

599 //= INFO: set global lock variable, non-blocking 

600 /////////////////////////////////////////////////////////////////////////////// 

601 MPR0C( setlock = "proc( lid ) 

602 begin globale( 1, lid, TRUE ) 

603 end_proc" 

604 ) 

606 /////////////////////////////////////////////////////////////////////////////// 

608 //= PROC: unsetlock 

609 //= IIFO: set global lock variable 

610 /////////////////////////////////////////////////////////////////////////////// 

611 HPR0C( unsetlock = "proc( lid ) 

612 begin globale( 1, lid, FALSE ) 

613 end_proc" 

614 ) 

616 /////////////////////////////////////////////////////////////////////////////// 

618 //= PROC: initsem 

619 //= INFO: init global semaphore variable 

620 /////////////////////////////////////////////////////////////////////////////// 

621 HPR0C( initsem = "proc( lid, n ) 

622 begin globale( 1, lid, n ) 

623 end.proc" 

624 ) 

626 /////////////////////////////////////////////////////////////////////////////// 

628 II- PROC: spinsem 

629 //= INFO: acquire one instance of shared resource, blocking 

630 /////////////////////////////////////////////////////////////////////////////// 

631 HPR0C( spinsem = "proc( lid, n ) 

632 begin while globale( 1, lid, m€tx(0, globaled, lid)-l)) = 0 do end_while; 

633 end_proc" 

634 ) 

636 lllllllllllllllllllllllllllllllllllllllllllllllllllllllllllllllllllllllllllllll 
638 //= PROC: acquiresem 
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639 //= IIFO: acquire one insteince of shared resource, non-blocking 

640 /////////////////////////////////////////////////////////////////////////////// 

641 HPR0C( acquiresem = "proc( lid, n ) 

642 begin bool(globale( 1, lid, max(0, globaled, lid)-l)) = 0) 

643 end_proc" 

644 ) 

646 /////////////////////////////////////////////////////////////////////////////// 

648 //= PROG: freesem 

649 //= INFO: free one instance of shared resource 

650 /////////////////////////////////////////////////////////////////////////////// 

651 HPR0C( freesem = ”proc( lid, n ) 

652 begin globaleC 1, lid, globale( 1, lid ) + 1 ) 

653 end.proc" 

654 ) 

656 /////////////////////////////////////////////////////////////////////////////// 

658 //= PROG: compute 

659 //= INFO: conpute a job on several (All) clusters 

660 /////////////////////////////////////////////////////////////////////////////// 

661 HPR0G( compute = ”proc( _cset_, _job_ ) 

662 local _c_; 

663 begin 

664 if( _cset_ = hold(All) ) then 

665 _cset_:= { _c_ $ _c_=l .. topology 0 }; // all clusters 

666 end^if; 

667 if( domtype(_cset_) <> D0H_SET ) then 

668 error (\"D0M_SET or option ’All’ expected as first argument\"); 

669 end_if; 

670 _cset_:= _cset_ minus { 1, topology (Gluster) }; // without me emd master 

671 

672 for _c_ in _cset_ do 

673 writequeueC \"work\", _c_, _job_ ); 

674 end_for; 

675 _cset_ ; 

676 end.proc" 

677 ) 

679 /////////////////////////////////////////////////////////////////////////////// 

681 //= PROG: define 

682 //= INFO: define an identifier on several (All) clusters 

683 /////////////////////////////////////////////////////////////////////////////// 

684 MPR0G( define = "proc( _cset_, _var_ : D0H_IDENT, _val_ ) 

685 begin net :: compute ( _cset_ , hold (.assign) (_veir_ , _val_) ); 

686 end.proc" 

687 ) 



Refer to the directory demo/NET/ on the CD-ROM for additional information. 

The dynamic module net was developed and implemented in cooperation with 
Torsten Metzner and Manfred Radimersky from the Fachbereich Mathematik, 
Universitat Paderborn, Germany. Many thanks to Stefan Wehmeier and Cris- 
topher Creutzig for testing and developing the macro parallel algorithms. This 
project was funded by the Sonderforschungsbereich 376^ Massive Parallelitat. 



10.7 Miscellaneous 



This section demonstrates that Motif Widgets, PASCAL routines and POSIX 
threads can be used within modules. It also shows how to create scanner mod- 
ules (to read formated text files) using the lexical analyzer generator flex. 
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10.7.1 Including Motif Widgets 

This example describes the usage of the Motif/Xll libraries within dynamic 
modules. The module demonstrated below contains a function new which allows 
the Mu PAD user to create simple Motif menu bars. The menu item selected with 
the mouse is returned as a Mu PAD character string (refer to figure 10.2). 




» q ### 

demo 

demo Ardbeg 1975 Glenfarcles 15 y.o* Glencadam 1978 



* # MuPAD 1.4*1 — Multi Processing Algebra Data Tool 

/\ /I 

* * I Copyright (c> 1997 - 98 by SciFace Software GmbH 

! #— 1-* All rights reserved. 

\/ 1 / 

»- — * UNREGISTERED VERSION 

Please contact info@sciface.com to register. 



» moduletmotif ); 

» choice;= motif:jnew( "### The HuPAD Whisky Bar ###", 

(!.> C "Ardbeg 1975", "Glenfarcles 15 y.o.", "Glencadam 1978" ] >: 

D 



Figure 10.2: Using Motif Widgets within Dynamic Modules 
The main C/C++ source file of the dynamic module motif is listed below: 



2 


/* 


FILE : 


motif .C — Modul - Hotif-Dialog-Toolbox 


♦/ 


3 


1 * 


AUTHOR : 


Andreas Sorgatz 


♦/ 


4 


/♦ 


DATE : 


30/03/98 


♦/ 



6 #define BOOL muff // undefine conflicting object 

7 #include "motif. H" 

8 

9 ///////////////////////////////////////////////////////////////////////////// 

10 HFUNCC yesno, HCnop ) 

11 { Widget root, menubar, menu; 

12 root = DIAguiRoot( "Yes/Ho" ); 






Miscellaneous 



185 



13 menubar = DIAguiNenuBar( root , "menubar" ) ; 

14 menu = DIAguiNenu( menubar, "Yes", DIAclbText, "Yes" ); 

15 menu = DIAguiNenuC menubar, "lo", DIAclbText, "lo" ); 

16 XtNanageChild( menubar ) ; 

17 DIAguiEventLoopO ; 

18 HFreturnC HFstring(DIAexitValue() ) ); 

19 } HFEID 

20 ///////////////////////////////////////////////////////////////////////////// 

21 HFUICC new, MCnop ) 

22 { Widget root, widget; 

23 long i; 

24 MTcell arg, tmp; 

25 HFnargsCheckC 2 ) ; 

26 HFargCheck ( 1 , DOH_STRIIG ) ; 

27 HFargCheck ( 2, DOH.LIST ); 

28 root = DIAguiRootC HFstring(MFarg(l) ) ); 

29 arg = HFarg(2) ; 

30 widget = DIAguiHenuBar ( root, "menubar" ); 

31 for( i=0; i < HFnops(arg); i++ ) { 

32 if( !HFisString(tmp=MFgetList(&arg,i) ) ) { 

33 DIAguiDestroyO ; 

34 HFerrorC "Invalid dialog definition" ) ; 

35 } 

36 DIAguiHenu( widget, HFstring(tmp) , DIAclbText, HFstring(tmp) ); 

37 } 

38 if( MFnops(arg) == 0 ) DIAguiMenuC widget, "Exit", DIAclbText, "Exit" ); 

39 XtHemageChildC widget ) ; 

40 DIAguiEventLoopO; 

41 HFreturnC HFstringCDIAexitValueO ) ); 

42 } HFEID 

Refer to the directory demo/MOTIF/ on the CD-ROM for additional information. 



10.7.2 Integrating PASCAL Routines 

This example demonstrates the integration of PASCAL routines into modules. 
This feature strongly depends on the compilers installed on your system. Refer 
to your Pascal and C-f + compiler manuals for detailed information. 

This module is intended to be used on Solaris systems and does not run on 
Linux directly.^ It plays with character strings and uses basic arithmetics: 



» module (pascal ) : 




// load the module 


» pascal : :hello() ; 




// play around with 


Pascal-String: <hello world> 




// PASCAL strings 


» pascal :: inc(41) ; 




// and increment an 




42 


// integer number 



The module main source code file (see below) calls the PASCAL routine pHello, 
which creates a character string terminated by ’\0’ and lets it print by a C/C++ 
routine. The PASCAL routine pine increments an integer number of type long: 

^On Linux systems one can use the GNU Pascal compiler. For this, the Makefile as 
well as the C/C-f-1- and Pascal source code must be adapted. 
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1 /////////////////////////////////////////////////////////////////////////////// 

2 // MODULE: pdemo.C 

3 // AUTHOR: Andreas Sorgatz (andi@mupad.de) 

4 // DATE : 31. Mar. 1998 

5 /////////////////////////////////////////////////////////////////////////////// 

6 HHG( Solaris: loption="-L/usr/local/lang/old/SUIHspro/lib -Ipc'* ) 

7 

8 extern "C" int plnc( int nura ); // Declaration of external Pascal routine 

9 extern "C" void pHelloO; // Declaration of external Pascal routine 

10 

11 /////////////////////////////////////////////////////////////////////////////// 

12 extern "C" void myCfun ( char *pstr ) //A routine to be called from Pascal 

13 { HFprintfC "Pascal-String: <y*s>", pstr ); 

14 } 

15 /////////////////////////////////////////////////////////////////////////////// 

16 HFUHC( inc, HCnop ) // Incrementing an integer using a Pascal routine 

17 { HFnargsCheckC 1 ); 

18 HFargCheck( 1, DOH.IHT ); 

19 HFreturn( HFlongC (long) pInc((int)HFlong(MFarg(l)))) ); 

20 } MFEND 

21 /////////////////////////////////////////////////////////////////////////////// 

22 HFUHC( hello, MCnop ) // Printing a character string using a Pascal routine 

23 { pHelloO; 

24 HFreturn( HFcopy (HVnull) ) ; 

25 } MFEHD 



The complete PASCAL code of the demonstrated module is listed here: 



1 .[:(c«4c***«*********4>********«*****>l<***«***************************’l‘*************} 



2 


{♦ 


FILE : 


libpascal.p 


♦} 


3 


{♦ 


AUTHOR: 


Andreas Sorgatz 


♦} 


4 


{♦ 


DATE : 


17. Dec. 1997 


♦} 



6 procedure myCfun ( var pstr: string ); external c; {* external Declaration ♦} 

7 

8 {♦ Simple Pascal routine 

9 function plnc( x: integer ) : integer; 

10 begin 

11 pine := x+1 ; 

12 end; 

13 

14 {* Pascal calls a C routine 

15 procedure pHello; 

16 var pstr : string; 

17 begin 

18 pstr:= ’hello world’ + chr(O) ; 

19 myCfun ( pstr ) ; 

20 end ; 

Refer to the directory demo/PASCAL/ on the CD-ROM for more information. 

10.7.3 Using POSIX Threads 

This example demonstrates the usage of POSIX threads within dynamic mod- 
ules. They can be used to implement parallel algorithms. This feature strongly 
depends on the compiler installed on your system. Refer to your C-f-f- com- 
piler manuals for detailed information. Refer also to section 9.2 for additional 
information about threads in Mu PAD. 
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The simple module pthread contains a function demo which starts two threads 
which are executed in parallel. This module function is not left before both 
threads are terminated. This example is intend to run with the Mu PAD kernel 
1.4.1 on Solaris and Linux systems only.^® 



» module (pthread) : 


// load the module 


» pthread: :demo() : 


// start two threads 


Start: rl=0, r2=0 




Task-1: Loop= 3 




Task-2: Loop= 3 




Task-2: Loop= 2 




Task-2: Loop= 1 




Task-1: Loop= 2 




Task-1: Loop= 1 




Sync : rl=ll, r2=22 





The complete source code of the dynamic module pthread is listed below: 

1 /////////////////////////////////////////////////////////////////////////////// 

2 // MODULE: pthr — Using Posix Threads 

3 // AUTHOR: Andreas Sorgatz (emdiQmupad.de) 

4 // DATE : 31. Mar. 1998 

5 /////////////////////////////////////////////////////////////////////////////// 

6 MMG( i386: loption = "-Ipthreads" ) // May not work on RedHat 

7 MMG( Solaris: loption = "-Ipthread" ) 

8 #if defined linux 

9 # include <pthread/mit/pthread .h> // Use MIT threads on Linux! 

10 #else 

11 # include <pthread.h> 

12 #endif 

13 

14 pthread_t t[2]; // handles for POSIX threads 

15 

16 /////////////////////////////////////////////////////////////////////////////// 

17 void taskK int *v ) 

18 { for( int i=4; i; i — ) { printfC "Task-1: Loop=*/,2d\n" , i ); sleep(2) ; } 

19 *v = 11; 

20 } 

21 void task2( int *v ) 

22 { for( int i=4; i; i — ) { printf( "Task-2: Loop=*/,2d\n" , i ); fflush(stdout) ; } 

23 *v = 22; 

24 } 

25 /////////////////////////////////////////////////////////////////////////////// 

26 MFUICC demo, MCnop ) 

27 { int rl=0, r2=0; 

28 printfC "Start: rl=*/,d, r2=*/,d\n" , rl , r2 ); 

29 pthread_create( &(t[0]), lULL, (void*(*) (void *)) taskl , &rl ); 

30 pthread_create( ft(t[l]), lULL, (void*(*) (void *)) task2 , &r2 ); 

31 pthread. join( t[0], HULL ); 

32 pthread. join( t[l] , HULL ); 

33 printfC "Sync : rl=*/,d, r2=*/,d\n" , rl , r2 ); 

34 MFreturnC MFcopy (MVnull) ) ; 

35 } MFEHD 

Refer to the directory demo/PTHREAD/ on the CD-ROM for more information. 

Older Mu PAD kernels or Mu PAD kernels compiled on other operating systems may not 
be linked with the thread library. 
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10.7.4 Creating Scanner Modules using flex 

flex (fast lexical analyzer generator) is a tool for generating scanners: programs 
which recognized lexical patterns in text, flex is the GNU version of lex which 
is distributed with UNIX operating systems. Refer to the corresponding UNIX 
manuals for additional information. 

This example demonstrates how scanner modules for analyzing text input files 
can be created using the shell script mkscan. As input the script expects a 
description of a scanner to generate (read the flex manual). For example: 



1 

2 

3 

4 

5 

6 

7 

8 
9 

10 

11 

12 

13 

14 

15 

16 

17 

18 

19 

20 
21 
22 

23 

24 

25 

26 

27 

28 

29 

30 

31 

32 

33 

34 

35 

36 

37 

38 

39 

40 

41 



/i(f4‘****************************************************************************/ 

/* FILE : scan.l - A sample of a scanner description file for (f)lex ♦/ 

/* AUTHOR : Andreas Sorgatz (andi@uni-paderborn.de) */ 

/* DATE : 01. Apr. 1998 */ 

/**4t*««*****4t4c«*4(**««*«**>l>***««*«*******************4t***««««*«***««4c«**««*««*«*/ 

/** Definiton of tokens: EOFILE=0 and UIKI0WI==1 must alluays be first. All ***/ 

/** tokens are non-negative integer. They will be returned by the function ***/ 
/** ’scan : : tokenO ’ . The rule for UHKIOHI tokens is defined with the module ***/ 
/** source code (refer to ’ECHO’ auid the manual of ’(f) lex’ ***/ 

U 

enum { E0FILE=O, UHKI0HH=1 , HEHLIIE, COMHEIT, IDEIT, IIT, FLOAT, STRUG }; 

y.} 



/*♦ Definition of regular expressions 
1**1 

wspace [\t ] 
nline [\n] 

Ccomment \/\/["\n]* 
comment {Ccomment} 

digit [0-9] 
letter [A-Za-z_] 



int {digit}+ 

float {digit}+(\.{digit}+)?((E|e) [+-] ?{digit}+)? 



ident {letter} ({letter} | {digit} ) * 
string 

/** The rules: the variable ’ScanLine’ is 

y.y. 

{wspace}+ { } 

{nline} { ++ScanLine; } 

{comment} { } 

{ident} { return( IDEHT ); } 

{int} { return( IHT ); } 

{float} { return ( FLOAT ) ; } 

{string} { return( STRING ) ; } 



defined in the module source code ***/ 

/* Eat up all whitespaces */ 

/* Eat up all linefeeds */ 

/♦ Eat up all comments */ 



y.y. 

/** User code, this section may contain help routines *♦*♦♦**♦♦♦*♦***♦♦**♦***♦*/ 



A MuPAD scanner module is then created by simply calling the shell script 

mkscan which also generates the corresponding module online documentation: 
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andi> mkscan scan 

## Creating (f)lex scanner source code ############################# 
scan.l ==> scan.yy.c 

## Creating the module source code ################################# 
mkscan ==> scan.C 

## Creating the module help file ################################### 
mkscan ==> scan.mdh 

## Compiling the dynamic scanner module ############################ 
scan.l, scan.C ==> scan.mdm 

MMG — MuPAD-Module-Generator — V- 1.4.0 Feb. 98 
Mesg. : Scanning source file ... 

[...] 

Mesg. : Ok 



The scanner module can now be used as shown in the example below. The 
values of token correspond to the definition in line 11 of the file scan.l. 



» module(scan) : // load scanner module 

» scan: :open("scan. i") : // open the input file 

» while( (t :=scan: : tokenO ) > 0 ) do // read until end-of-file 

&> print ( Unquoted, " line= " .expr2text(scan: :line()) . 

&> " token= " .expr2text(t) . " text= ". scan: : text () ); 

&> end_while: 

line= 7 token= 4 text= Dynamic 
line= 7 token= 4 text= modules 
line= 7 token= 4 text= are 
line= 7 token= 4 text= quite 
line= 7 token= 4 text= useful 
line= 11 token= 5 text= 42 
line= 11 token= 5 text= 666 
line= 15 token= 6 text= 1.2 
line= 15 token= 6 text= le-2 
line= 15 token= 6 text= l.Oe-2 
line= 19 token= 7 text= "Two" 
line= 19 token= 7 text= "strings" 
line= 23 token= 1 text= - 
line= 23 token= 1 text= + 

>> scan: : closeO : // close the input file 



Refer to the directory demo/FLEX/ of the CD-ROM for additional information. 




A. The Accompanying CD-ROM 



A.l Contents of the CD-ROM 

The accompanying CD-ROM contains a hypertext version of this book, Mu PAD 
1.4.1 for Linux and Solaris systems, the source code of all examples and module 
applications described in this book as well as binaries for most of them. 

The CD-ROM further contains contributions from other authors consisting of 
programs, libraries and C-t--f sources which are used by module applications. 

The contents of the CD-ROM is not public domain but copyrighted. Refer to 
the following sections for detailed information about the software systems and 
packages as well as their copyrights and license agreements. 



A.1.1 MuPAD 

The CD-ROM contains trial versions of MuPAD. Refer to the sections A. 2 Sys- 
tem Requirements^ A. 3 Installation and A. 4 License Aggreements for details. 



A.1.2 ASAP 

What is it: ASAP [6] is a handy interprocess communication protocol to 
exchange mathematical data encoded as attributed trees, called the asap terms. 
The leaves of the trees can be 32 bits (signed) integers or arbitrary binary data. 

Developers: ASAP -more exactly ASAP 2 - is developed by Stephane Dalmas 
and Marc Gaetano at INRIA Sophia Antipolis, projet SAFIR, 2004 route des lu- 
cioles, BP 93, 06902 Sophia- Antipolis, France. The developers can be contacted 
via email at {stephane. dalmas, marc.gaetano}@sophia.inria.fr. 

Usage: ASAP is used to demonstrate the integration of interprocess commu- 
nication protocols in MuPAD. Refer to section 10.6.1 for a description. 
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Documentation: The directory demo/ASAP/doc/ on the CD-ROM contains a 
manual (6 p.) with an introduction to ASAP and the list of functions available. 

License: Not available. 

A. 1.3 GB and RealSolving 

What is it: GB stands for Grobner Basis and is a system to compute complex 
Grobner basis in an extremly efficient way. RealSolving is a system to find and 
classify real roots of huge polynomials. Both software systems perform exact 
computations that make, in particular, their results safe. 

Developers: GB is developed by Jean-Charles Faugere, Equipe Calcul Formel, 
Paris, France (jcf@calfor.lip6.fr). RealSolving is developed by Fabrice Rouillier, 
Loria (INRIA-Lorraine), Nancy, France (Fabrice.Rouillier@loria.fr). 

Usage: Mu PAD performs a fiexible interface to GB and RealSolving. Section 
10.5.3 demonstrates the usage of both systems from within Mu PAD. 

Documentation: An english tutorial for GB is available via the world-wide- 
web at http://posso.lip6.fr/~jcf/Introduction/Introduction.html. The direct- 
ory demo/GBRSOLVE/doc/ on the CD-ROM contains a manual about the Mu PAD 
GB I RealSolving interface (~25 p.) and a RealSolving manual (~220 p.). Refer 
to http://www.loria.fr/~rouillie/MUPAD/gbreso.htmlfor more information. 

License: For detailed information about copyrights and license agreements 
refer to the file demo/GBRSOLVE/doc/COPYING on the CD-ROM. 



A.1.4 GMP 

What is it: GNU MP is a library for arbitrary precision arithmetic, operating 
on signed integers, rational numbers, and fioating point numbers. It has a rich 
set of functions, and the functions have a regular interface. 

Developers: The GMP Library is developed under the terms of the GNU 
Library General Public License as published by the Free Software Foundation. 
The developers can be contacted via email at bug-gmp@prep.ai.mit.edu. Refer 
to the documentation for detailed information. 

Usage: Section 10.4.1 demonstrates the integration of GMP, respectively of 
algorithms written by use of GMP, in Mu PAD. GMP may also be used to 
transfer arbitrary precision numbers in the context of MP (section A. 1.6). 

Documentation: The directory demo/GMP/doc/ on the CD-ROM contains a 
complete reference manual (~40 p.). 

License: GMP is available under the GNU Library General Public License. 
Refer to the file demo/GMP/gmp/COPYING .LIB for detailed information. 
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A.1.5 MAGNUM 

What is it: Magnum is a C++ class library with fast factorisation algorithms 
for univariate polynomials over finite fields. 

Developers: Magnum has been developed in a master thesis by Wolfgang 
Roth, Universitat Mannheim, Fakultat fiir Mathematik und Informatik. 

Usage: Section 10.5.1 demonstrates the integration of Magnum in Mu PAD. It is 
used to accomplish very fast factorisations of univariate polynomials over finite 
fields ¥p with a prime p 

Documentation: The directory demo/MAGNUM/doc/ on the CD-ROM contains 
the master thesis (~50 p.) and an introduction to the Magnum C++ classes (5 
p.). Both documents are written in german. 

License: Magnum is available under the terms of the GNU General Public 
License respectively the GNU Library General Public License as published by 
the Free Software Foundation. The developer can be contacted via email at 
roth@math.uni-mannheim.de. Refer to the documentation for details. 

A.1.6 MP 

What is it: MP [13] [14] is an interprocess communication protocol to exchange 
mathematical data encoded as attributed syntax trees. It is designed for ex- 
ploring issues in integrating symbolic, numeric, graphics, document processing, 
and other software tools for scientific computation within different computing 
paradigms (e.g., point to point, distributed, parallel, software bus). 

Developers: MP is developed and maintained by S. Gray (Ashland University, 
Ashland, Ohio), N. Kajler (Ecoles des Mines, Paris) and P. Wang (Kent State 
University, Kent, Ohio) with contributions from other authors. 

Usage: MP is used to demonstrate the integration of interprocess communic- 
ation protocols in Mu PAD as described in section 10.6.2. It is also used to 
interact with the computer algebra system Singular [3] (section A. 1.9). MP is 
a C library package and can be linked to other user applications. 

Documentation: The directory demo/MP/doc/ on the CD-ROM contains a 
complete reference manual (~60 p.). An introduction including license inform- 
ation is available with the file demo/MP/doc/README. 

License: MP can be used for non-commercial purposes. Refer to the docu- 
mentation for detailed license information. 
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A.1.7 NTL 

What is it: NTL is a high-performance, portable C++ library providing data 
structures and algorithms for manipulating signed, arbitrary length integers, 
and for vectors, matrices, and polynomials over the integers and finite fields. 

Developers: NTL is written and maintained by Victor Shoup with some con- 
tributions from other authors. The developer can be contacted via email at 
shoup@cs.wisc.edu. Refer to http://www.cs.wisc.edu/ shoup/ntl/ for details. 

Usage: Section 10.5.2 demonstrates the integration of NTL, respectively of 
algorithms written by use of NTL, in Mu PAD. It is used to accomplish very fast 
factorisations of univariate polynomials over the integers. 

Documentation: The directory demo/NTL/doc/ on the CD-ROM contains a 
manual (16 p.) with an introduction to the NTL C++ classes. 

License: NTL is intended for research and educational purposes only. Refer 
to the documentation for more details. 

A.1.8 PVM 

What is it: PVM is a system that enables a collection of heterogeneous com- 
puters to be used as a coherent and flexible concurrent computational resource. 

Developers: PVM is developed by J. J. Dongarra, G. E. Fagg, G. A. Geist, J. 
A. Kohl, R. J. Manchek, P. Mucci, P. M. Papadopoulos, S. L. Scott, and V. S. 
Sunderam at the University of Tennessee, Knoxville TN., Oak Ridge National 
Laboratory, Oak Ridge TN., Emory University, Atlanta GA. 

Usage: PVM is used to demonstrate the integration of network services in 
MuPAD as described in section 10.6.3. PVM is a C library package and can be 
linked to other user applications. 

Documentation: The directory demo/NET/doc/ on the CD-ROM contains a 
complete reference manual (~280 p.). 

License: PVM can be used for any purpose and without fee. Refer to the file 
demo/NET/Readme for detailed license information. 



A. 1.9 Singular 

What is it: Singular [15] is a computer algebra system for commutative al- 
gebra, algebraic geometry and singularity theory. 

Developers: Singular is created and its development is directed and coordin- 
ated by G.-M. Greuel, G. Pfister and H. Schonemann with contributions by 0. 
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Bachmann, W. Decker, H. Grassmann, B. Martin, M. Messollen, W. Neumann, 
T. Nuessler, W. Pohl, T. Siebert, R. Stobbe and T. Wichmann at Fachbereich 
Mathematik und Zentrum fur Computeralgebra, Universitat Kaiserslautern, 
67653 Kaiserslautern, Germany. 

Usage: Singular is used by the Mu PAD library sing [3] (section 10.5.4) and 
provides, among others, very fast Grobner basis computations. It can be run as 
standalone and independent program by calling the script demo /bin/ singular 
on the CD-ROM. 

Documentation: The directory demo/SINGULAR/doc/ on the CD-ROM con- 
tains a tutorial (~60 p.) and a complete reference manual (~200 p.). 

License: For detailed information about copyrights and license agreements 
read the file demo/SINGULAR/doc/COPYING on the CD-ROM or refer to the web 
page http : //www . mathemat ik . uni-kl . de/ ~zca/ Singular. 



A. 2 System Requirements 

To use the CD-ROM, one of the following system configurations is required: 

Linux 2.0: (tested with S.u.S.E} 5. 1/5.2, Debian) 

• IBM PC-compatible ix86 (Pentium recommended) with CD-ROM drive 

• 16MB main memory (32MB recommended) 

• 1MB free disk space to use CD-ROM examples 

• about 180MB for a complete installation on hard disk 

• ELF binary support (this is the default since kernel version 2.0) 

Solaris 2.5: (also tested with Solaris 2.6) 

• SunSPARC workstation with CD-ROM drive 

• 32MB main memory (48MB recommended) 

• 1MB free disk space to use CD-ROM examples 

• about 180MB for a complete installation on hard disk 

Although the binaries cannot be used on other operating systems, most ex- 
amples and module applications (available as C/C-f-f source code) may also 
work with other UNIX systems. Minor changes according to special system 
and/or compiler features may be needed. For details refer to the information 
given with the corresponding examples in section 10. 



^Refer to http://www.suse.de for further information. 
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A. 3 Installation 

To run Mu PAD and the module binaries from the accompanying CD-ROM, the 
CD-ROM must be mounted and UNIX as well as Mu PAD environment variables 
should be configured. 

To create binaries from the sources available on the CD-ROM, also a GNU g++ 
compiler (version 2.7.2 or later) must be installed on your local system. 

For information about the license agreements for the software available on the 
CD-ROM, please refer to section A. 4 as well as the sections A. 1.2- A. 1.9. 



A. 3.1 Using the CD-ROM Live System 

Follow the instructions below to configure your local system to use Mu PAD as 
well as the examples from the CD-ROM: 

1. Mount the CD-ROM by using the corresponding UNIX command: 

mount / cdrom (on Linux systems) 

volcheck (on Solaris systems) 

The CD-ROM will be mounted at /cdrom on a Linux system and at 
/cdrom/cdromO on a Solaris system. In all following descriptions it 
is assumed that the CD-ROM is mounted at /cdrom. 

If you cannot mount the CD-ROM in this way then ask your system 
administrator for information about your local configuration. 

To start MuPAD, execute either the shell-script /cdrom/ start me or call 
it directly by executing /cdrom/share/bin/mupad (terminal version) or 
/cdrom/ share/bin/xmupad (XView/Xll version). 

To read the online version of this book start /cdrom/share/bin/dynmod 
or type the command Tdynmod^ within xmupad. 

2. For your convenience expand the environment variable path -when using 
csh or tcsh- by including the following command at the end of your 
personal file ~/ . cshrc: 

set path = (/cdrom/ share/bin $path) 

Expand the environment variable PATH by including the following com- 
mand at the end of your personal file ~/. profile when using the sh, 
bash or ksh: 

PATH=/cdrom/share/bin : $PATH 

^Also information about all MAPI routines are available in this way. For example, type 
7MFUNC to read how to define module functions. 
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Execute the corresponding command directly within your shell to make 
this definition available instantly. 

3. To use the module application net (MuPAD macro parallelism) the envir- 
onment variable MuPAD_R00T_PATH must be set to the CD root directory 

(/cdrom). This definition must be inserted into your personal file 
~/.cshrc respectively ~/. profile. 



A. 3. 2 Installation on Hard Disk 

MuPAD can be installed on a hard disk by carrying out the following tasks: 

1. Mount the CD-ROM as described above. 

2. Create a directory on your hard disk, e.g. /usr/local/MuPAD 
mkdir /usr/local/MuPAD 

3. Copy the contents of the CD-ROM in the new MuPAD directory and 
remove write protection: 

cp -r /cdrom/* /usr/local/MuPAD 
chmod -R u+w /usr/local/MuPAD 

If there is not enough memory available on your hard disk, you need not 
to copy the sub-directory /cdrom/demo. In order to use the examples and 
module applications just create a link to it: 

In -s /cdrom/demo /usr/local/MuPAD/demo 

4. Change the variables listed in section A. 3.1 according to your need. 

To change examples and module applications or to recompile them, the contents 
of / cdrom/demo (respectively corresponding parts of it) must be copied on your 
local hard disk. 



A. 4 MuPAD License Agreements 

The MuPAD versions distributed with the accompanying CD-ROM are trial 
versions which do not include a MuPAD user license. They contain a memory 
limitiation which can be unlocked with a license key after MuPAD is registered. 
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A.4.1 General License 

MUPAD 1.4.1 END USER LICENSE AGREEMENT 

Part I applies if you have not purchased a license to the accompanying software (the ’’Soft- 
ware”). Part II applies if you have purchased a license to the Software. Part III applies to 
all license grants. If you wish to purchase a license, contact SciFace Software GmbH k Co. 
KG (’’SciFace”) at Technologiepark 12, D-33100 Paderborn, Germany or send an email to 
infoCsciface.com or use the online service www.sciface.com. 

Special licenses for members of non-profit educational and scientific institutions are available. 
Please read section A. 4. 2. 

PART I - Trial License 

SciFace grants you a non-exclusive single-user license to use the Software free of charge if 
your use of the Software is for the purpose of evaluating the Software. The evaluation period 
is limited to 30 days. You may use the Software in the manner described in Part II below 
under ’’Scope of Grant.” 

DISCLAIMER OF WARRANTY 

Free of charge Software is provided on an ”AS IS” basis, without warranty of any kind, 
including without limitation the warranties of merchantability, fitness for a particular purpose 
and non-infringement. The entire risk as to the quality and performance of the Software is 
borne by you. Should the Software prove defective, you and not SciFace assume the entire 
cost of any service and repair. This disclaimer of warranty constitutes an essential part of 
the agreement. 

Even if parts of the disclaimer violates legal rights of some jurisdiction, only these parts are 
invalid, but not the entire disclaimer. 

PART II - Single-user License 

Subject to payment of applicable license fees, SciFace grants to you a non-exclusive license 
to use the Software and accompanying documentation (’’Documentation”) in the manner 
described in Part III below under ’’Scope of Grant.” 

LIMITED WARRANTY 

SciFace warrants that for a period of ninety (90) days from the date of acquisition, the 
Software, if operated as directed, will substantially achieve the functionality described in the 
Documentation. SciFace does not warrant, however, that your use of the Software will be 
uninterrupted or that the operation of the Software will be error-free. SciFace also warrants 
that the media containing the Software, if provided by SciFace, is free from defects in material 
and workmanship and will so remain for ninety (90) days from the date you acquired the 
Software. SciFace’s sole liability for any breach of this warranty shall be: 

(a) to replace your defective media; or 

(b) to advise you how to achieve substantially the same functionality with the Software as 
described in the Documentation; or 

(c) if the above remedies are impracticable, to refund the license fee you paid for the Software. 
Repaired, corrected, or replaced Software and Documentation shall be covered by this limited 
warranty for the period remaining under the warranty that covered the original Software, or 
if longer, for thirty (30) days after the date 

(a) of shipment to you of the repaired or replaced Software, or 

(b) SciFace advised you how to operate the Software so as to achieve the functionality de- 
scribed in the Documentation. 
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Only if you inform SciFace of your problem with the Software during the applicable warranty 
period and provide evidence of the date you purchased a license to the Software will SciFace 
be obligated to honor this warranty. SciFace will use reasonable commercial efforts to repair, 
replace, advise or, for individual consumers, refund pursuant to the foregoing warranty within 
30 days of being so notified. 

This is the only warranty made by SciFace. SciFace makes no other express warranty and 
no warranty of noninfrigment of third parties’ rights. The duration of implied warranties, 
including without limitation, warranties of merchantability and of fitness for a particular 
purpose, is limited to the above limited warranty period. 

Even if parts of the limited warranty violates legal rights of some jurisdiction, only these parts 
are invalid, but not the entire warranty. 

If any modifications are made to the Software by you during the warranty period; if the 
media is subjected to accident, abuse, or improper use; or if you violate the terms of this 
Agreement, then this warranty shall immediately be terminated. This warranty shall not 
apply if the Software is used on or in conjunction with hardware or software other than the 
unmodified version of hardware and software with which the software was designed to be used 
as described in the Documentation. 

PART III 

SCOPE OF GRANT 
You may: 

• use the Software on any single computer; 

• use the Software on a network, provided that each person accessing the Software through 
the network must have a copy licensed to that person; 

• use the Software on a second computer as long as only one copy is used at a time; 

• copy the Software for archival purposes, provided any copy must contain all of the original 
Software’s proprietary notices. 

You may not: 

• permit other individuals to use the Software except under the terms listed above; 

• permit concurrent use of the Software; 

• modify, translate, reverse engineer, decompile, disassemble or create derivative works based 
on the Software; 

• copy the Software other than as specified above; 

• rent, lease or otherwise transfer rights to the Software; or 

• remove any proprietary notices or labels on the Software. 

TITLE 

Title, ownership rights, and intellectual property rights in the Software shall remain in SciFace 
and/or its suppliers. The Software is protected by the copyright laws and treaties. Title and 
related rights in the content accessed through the Software is the property of the applicable 
content owner and may be protected by applicable law. This License gives you no rights to 
such content. 

TERMINATION 

The license will terminate automatically if you fail to comply with the limitations described 
herein. On termination, you must destroy all copies of the Software and Documentation. 
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A.4.2 Educational License 

MUPAD 1.4.1 END USER LICENSE AGREEMENT FOR MEMBERS OF NON-PROFIT 
EDUCATIONAL AND SCIENTIFIC INSTITUTIONS 

If you have any questions concerning the license to the accompanying software (the "Soft- 
ware”) or if you wish to purchase a license, please contact SciFace Software GmbH & Co.KG 
("SciFace”) at Technologiepark 12,D-33100 Paderborn, Germany or send an email to 
inf oOscif ace . com or use the online service www. seif ace . com. 

SciFace grants you a non-exclusive single-user license to use the Software free of charge if you 
are a student, faculty member or staff member of an educational institution (junior college or 
college), a staff member of a non-profit research institution, or an employee of an organization 
which meets SciFace ’s criteria for a charitable non-profit organization. Government agencies 
are not considered educational or charitable non-profit organizations for purposes of this 
Agreement. 

Free of charge licenses are not available for the following version of the Software: MuPAD 
Pro for Windows 95. Please contact SciFace to get information about special rates. 

If you fit within the description above, you may use the Software in the manner described in 
"Scope of Grant.” 

If you don’t fit within the description above, you can use this version of MuPAD free of charge 
if your use of the Software is for the purpose of evaluating the Software. The evaluation period 
is limited to 30 days. Please read section A.4.1. 

DISCLAIMER OF WARRANTY 

Free of charge Software is provided on an "AS IS” basis, without warranty of any kind, 
including without limitation the warranties of merchantability, fitness for a particular purpose 
and non-infringement. The entire risk as to the quality and performance of the Software is 
borne by you. Should the Software prove defective, you and not SciFace assume the entire 
cost of any service and repair. This disclaimer of warranty constitutes an essential part of 
the agreement. 

Even if parts of the disclaimer violates legal rights of some jurisdiction, only these parts are 
invalid, but not the entire disclaimer. 

SCOPE OF GRANT 
You may: 

• use the Software on any single computer; 

• use the Software on a network, provided that each person accessing the Software through 
the network must have a copy licensed to that person; 

• use the Software on a second computer as long as only one copy is used at a time; 

• copy the Software for archival purposes, provided any copy must contain all of the original 
Software’s proprietary notices. 

You may not: 

• permit other individuals to use the Software except under the terms listed above; 

• permit concurrent use of the Software; 

• modify, translate, reverse engineer, decompile, disassemble or create derivative works based 

on the Software; 

• copy the Software other than as specified above; 

• rent, lease, grant a security interest in, or otherwise transfer rights to the Software; or 

• remove any proprietary notices or labels on the Software. 
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TITLE 

Title, ownership rights, and intellectual property rights in the Software shall remain in SciFace 
and/or its suppliers. The Software is protected by the copyright laws and treaties. Title and 
related rights in the content accessed through the Software is the property of the applicable 
content owner and may be protected by applicable law. This License gives you no rights to 
such content. 

TERMINATION 

The license will terminate automatically if you fail to comply with the limitations described 
herein. On termination, you must destroy all copies of the Software and Documentation. 



A. 4. 3 How to Register MuPAD 

When registering MuPAD with a license key, memory limitations are removed 
and your copy of MuPAD becomes a full version. Note, that MuPAD has to be 
installed on disk before entering the license key, because registration does not 
work on write protected media. 

Refer to the web at http://www.sciface.com/products/licenses.shtmlfor 
further information and to obtain a MuPAD license key. On questions please 
send an email to infoOsciface.com or contact: 



Sci 

Interfaces 



SciFace Software GmbH & Co. KG 
Technologiepark 12 
D-33100 Paderborn 
Germany 

Fax +49-5251-6407-99 , Web http://www.sciface.com 




B. Changes 



B.l With Respect to Release 1.2.2 

• completely redesigned kernel programming interface 

• switch from ANSI-C to C++ support 

• option -gcc of mmg was changed to -gnu 

• sources can be split into several files to support the use of make 



B.2 With Respect to Release 1.3.0 

• extended MuPAD (kernel) application programming interface {MAPI): 

- easy handling of MuPAD variables 

- full access to MuPAD domains and their elements 

- easy access to the module domain 

- temporary static modules, attribute can be changed at run-time 

- extended evaluation routines (statements, secure context, . . .) 

- meta types of basic MuPAD data types for fast type checking 

- support of variables which are protected from garbage collection 

- handling of 2 and 3-state boolean logic 

- converting routines for arrays and polynomials 

- a selection of basic arbitrary precision arithmetic functions 

• MuPAD release 1.4 does not support the toolbox routines which were 
defined in MMT_tool.c (MuPAD release 1.2.1) anymore 
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• -op path can be used to instruct the module generator to store output 
files in the directory path 

• the order of the parameters of function external and module : :func was 
changed from external (fun, mod) to external (mod, fun) 

• MPROC and MEXPR can be used to include Mu PAD procedures and expres- 
sions into a module domain 

• new preferences to support the implementation of module applications: 
Pref : :userOptions, Pref : rcallBack and Pref : :callOnExit 

• the new default compiler of mmg is now the compiler which was used to 
create the Mu PAD kernel binary 

• option -nognu instructs mmg to use an alternative C++ compiler 

• due to a new memory management used by the Mu PAD kernel, to create 
a dynamic module the mmg default compiler must be used. Otherwise the 
kernel may quit with the error message . . .unresolved symbols. . . when 
loading or using the module 

• better support of linking object and archive files 



B.3 Latest News and Changes 

For latest news about dynamic modules as well as updates and bug fixes con- 
cerning dynamic modules and the MuPAD Application Programming Interface 
refer to the MuPAD web site at: 



http : //www . mupad . de/PAPER/MODULES/ 
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1.4.0 Last change: 17 December 1997 MMG(l) 

- MuPAD module generator for creating dynamic modules 

[-a {static (unload}] [-c main=name] [-check] [-generic] 
[-gnu] [-j {fund table I link}] [-n] [-nog] [-noc] [-nol] 
[-pseudo] [-sys] [-v] [-V text] [-CC ccnam] [-LD Idnam] 
[-OC copt] [-ol lopt] [-Ddef] [-Ipath] [-llib] [-Lpath] 
[-nop] [-nor] [-nognu] [-op path] [-g] [-color] file.C 
[f ile.o . . .] 

DESCRIPTION 

mmg is the module generator of MuPAD. It analyzes a module 
source file written in the programming language C++ (inclu- 
ding additional special commands for mmg) and translates it 
into a loadable and executable dynamic MuPAD module. 

In addition to its options, mmg accepts the name of one C++ 
source file with any suffix valid for your C++ compiler and 
a list of object files ’file. o’, that are to be linked to 
the module. Depending on the options, additional C++ code 
for the module management is generated and written into the 
temporary file ’MMGsource.C’ . This file includes the user’s 
source code and will be compiled by a C++ compiler and 
linked into a dynamic module by generating an object file 
’source. o’ and a shared library ’ source .mdm’ . By default, 
all output files are placed in the current directory. 

By default, for creating module binaries mmg uses the C++ 
compiler that was used to compile the MuPAD kernel. This is 



MMG Rel. 
NAME 

mmg 

SYNOPSIS 

mmg 
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either the standard C++ compiler distributed with your 
operating system (e.g. CC, cxx, xlC) or the GNU g++ compiler 
and the link editor Id. This varies for different operating 
systems and MuPAD releases as well as for different machine 
types. However, the user can change the default value by 
setting the option -gnu respectively -nognu, in order to use 
respectively use not the GNU compiler g++, or by redefining 
the compiler and linker name with option -CC, -LD respec- 
tively. Note: Dynamic modules must be compiled to position 
independent code (PIC). It is always recommended to use the 
default compiler. 

OPTIONS 

-a attr 

Sets the attribute attr to specify a special treatment 
of this module: 

static - MuPAD never unloads this module 
unload - MuPAD unloads it as fast as possible 

-c main=name 

This is used to compile a source file that is part of a 
module name to an object file. Object files like this 
can be linked to a module later, mmg creates the object 
file ’source. o’ and a temporary file ’MMGsource.C’ , 
which contains relevant parts of the module management 
code. This option must not be used to compile the main 
source file of the module! 

-color 

Colors the messages of mmg, which makes it easier to 
distinguish comments, warnings and errors in a multiple 
line output. This option is interpreted by the shell 
script mmg and ignored by the corresponding binary. 

-check 

Combination of -j link and -nol. mmg checks the stati- 
cal semantics of MuPAD kernel function calls. The value 
link enables the C++ compiler to make a full analysis 
by using MuPAD function prototypes. 

-g Debug option. This is a combination of option -nor and 
-oc -g. mmg instructs the C++ compiler to create code 
which can be debugged with gdb respectively dbx. 

-gnu Instructs mmg to use g++ instead of the standard C++ 
compiler of the operating system. 
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-nognu 

Instructs mmg to use the standard C++ compiler of the 
operating system instead of the GNU compiler g++ . 

-generic 

Instructs mmg to create a module for the ’generic* 
MuPAD kernel (for wizards only) . 

-j mode 

Selects the method of address evaluation for MuPAD ker- 
nel objects: 

func - via a function call (default) 

table - via an address table 
link - via the dynamic link editor 
Using special low-level functions of the MuPAD kernel 
may require to set option -j link (for wizards only) . 

-n No operation. Suppress any kind of code generation. In 
combination with the option -v it can be used to check 
the calling sequence of the compiler and linker. 

-nog Instructs mmg to skip the generation of module manage- 
ment code. It is expected that this was done before and 
the file ’MMGsource .C’ , containing the module manage- 
ment code, is placed in the current directory. If this 
code has not been generated by mmg, the user himself 
has to guarantee the correct handling of this module. 

-noc Instructs mmg to skip the compilation of the extended 
module source code. It is expected this was done before 
and the object file ’MMGsource.o’ is placed in the 
current directory. 

-nol Suppress linking. Depending on the further options, mmg 
only generates the file ’MMGsource.C’ and compiles it 
to an object file ’MMGsource .o’ . 

-nop Instructs mmg not to use its internal preprocessor to 
expand mmg macros like MFUNC. This option is automati- 
cally set when using the MFUNC MFEND syntax (for 
wizards only) . 

-nor Instructs mmg not to remove the temporarily created 
code files ’MMGsource . C ’ and ’MMGsource.o’ . 
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-op path 

Changes the output directory for created files from the 
current working directory to path. 

-pseudo 

Instructs mmg to generate module management code for a 
pseudo module. This may be compiled and linked stati- 
cally to the MuPAD kernel. This is used on systems 
which do not support true dynamic modules. The name of 
the output file is ’pmodule.c’ (for wizards only). 

-sys Returns the system name. MuPAD uses this name to find 
system dependent binaries. Also refer to sysinfo. 

-V Verbose. Normally mmg does its work silently. Using -v 
mmg displays every step of the module generation. 

-V text 

Sets the user information string of the module to text. 
-CC ccnam 

Specifies the name of the C++ compiler. This overwrites 
the default value, the option -gnu and the value given 
in the environment variable MMG_CC. In addition to the 
name, the string ccnam may contain compiler options. 

-LD Idnam 

Specifies the name of the linker. This overwrites the 
default value and the value given in the environment 
variable MMG.LD. In addition to the name, the string 
Idnam may contain linker options. 

-oc copt 

Passes the option copt to the compiler. 

-ol lopt 

Passes the option lopt to the linker. 



-Ddef 

Defines the C++ preprocessor symbol def . Shortcut for 
-oc -Ddef. 



-Ipath 

Adds path to the list of directories in which to search 
for include files. Shortcut for -oc -Ipath. 
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-Lpath 

Adds the path to the list of directories in which to 
search for libraries. Shortcut for -ol -Lpath. 

-llib 

This option is an abbreviation for the library name 
liblib.*. Shortcut for -ol -llib. 



ENVIRONMENT 

MMG.CC 

Specifies the name (as well as default options) of the 
C++ compiler to be used by mmg. Refer to option -CC. 



MMG.LD 

Specifies the name (as well as default options) of the 
link editor to be used by mmg. Refer to option -LD. 

PATH mmg requires the insertion of the names of directories 
which contain the standard C++ compiler of your opera- 
ting system (e.g. CC, cxx or xlC) , the link editor Id 
and, if you want to use it, the GNU compiler g++ in 
your path list. 

NOTE If you have to use LD LIBRARY PATH, be sure to put the 
path of your C++ compiler at the head of the path list. 



FILES 

MMGsource .C 

source . o 
source .mdm 
source .mdg 
source.mdh 



extended source, including C++ code for module 
management . 

module object file, not linked 
loadable dynamic MuPAD module 
module procedures and expressions 
module online documentation 



SEE ALSO 

CC(1), cxx(l), xlC(l), g++(l), ld(l) 

For detailed technical information about dynamic modules and 
the implementation in MuPAD refer to the German MuPAD Report 

Dynamische Module — Eine Verwaltung fuer Maschinencode- 
Objekte zur Steigerung der Effizienz und Flexibilitaet 
von Computeralgebra-Systemen, Andreas Sorgatz, MuPAD 
Reports, October 1996, B.G. Teubner, Stuttgart (German) 
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DIAGNOSTICS 

The diagnostics produced by mmg are intended to be self- 
explanatory. Occasional obscure messages may be produced by 
the preprocessor, compiler, assembler, or loader. 



NOTES 

mmg generates additional C++ code for the module management. 
This is compiled and linked together with the user’s source 
code. In case of trouble (e.g. naming conflicts), check your 
source code for names that are also used in the file 
’MMGsource.C’ , temporarily created by mmg, or in the MuPAD 
header files that are installed in the directory 
$MuPAD ROOT PATH/share/mmg/ include. Never declare or define 
any object with a prefix MC, MD, MF, MT, MV. 

RESTRICTIONS 

The length of option strings is limited to 2000 characters. 
The number of module functions is limited to 512 per module. 

TECHNICAL SUPPORT 

For technical support send a detailed bug-report via email 
to <bugsOmupad . de> or <andi@mupad . de> . 




D. MAPI Short Reference 



Defining Module Functions 

MFUNC...MFEND Defines a module function 55 

Accessing Module Function Arguments 

MFarg Returns the n-th function argument 56 

MFargCheck Checks the type of the n-th function argument 56 

MFnargsCheck Checks the number of function arguments 57 

MFnargsCheckRange Checks the number of function arguments 57 

MVargs Sequence of function arguments 57 

MVnargs Number of function arguments 57 

Leaving Module Functions 

MFerror Aborts a module function with an error message 57 

MFreturn Returns the result of a module function 58 

Type Checking 

MFdom Returns the basic domain of an object 59 

MFis... Checks for a specific basic domain or a special object . . 60 

MFisApm Checks for arbitrary precision integer numbers 60 

MFisChar Checks for character based basic domains 60 

MFisExpr Checks for expressions 60 

MFisExt Checks for domain elements 60 

MFisIdent Checks for identifiers 61 

MFisInt Checks for machine integer numbers 61 

MFisInteger Checks for integer numbers 61 
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MFisNumber Checks for numbers 61 

MFisString Checks for character strings 61 

MFdomtype Returns the basic domain of an object 61 

MFtype Returns the type of an object 62 

MFtesttype Checks for specific types or data structures 62 

Comparing Objects 

MFcmp Compares with respect to the internal term order 63 

MFequal Equal with respect to the internal term order 63 

MFeq Equal with respect to the numerical order 63 

MFge Greater or equal with respect to the numerical order. . . 64 

MFgt Greater with respect to the numerical order 64 

MFle Less or equal with respect to the numerical order 64 

MFlt Less with respect to the numerical order 64 

MFneq Unequal with respect to the numerical order 64 

Converting Basic C/C++ Data Types 

MFbool Converts Boolean with respect to a 2-state logic 66 

MFbool3 Converts Boolean with respect to a 3-state logic 66 

MFdouble Converts floating point numbers 66 

MFfloat Converts floating point numbers 67 

MFident Converts identifier to C/CH— f- string and vice versa 67 

MFint Converts integer numbers less than 2^^ 67 

MFlong Converts integer numbers less than 2^^ 67 

MFstring Converts character strings 67 

Converting Arbitrary Precision Numbers 

MFpari Converts PARI to MuPAD numbers and vice versa 69 

Converting Strings from/to Expressions 

MF Constructs a MuPAD object from a C/C-H- string 69 

MFexpr2text Converts a MuPAD object into a C/C++ string 70 

MFtext2expr Converts a C/C++ string into a MuPAD object 70 

Basic Object Manipulation 

MFchange Physically copies a cell 70 

MFcopy Logically copies a cell 71 

MFfree Frees a cell 71 




Special Objects 



213 



MFnops Returns/Changes the number of operands 71 

MFmemGet Returns the memory block of a cell for reading 71 

MFmemSet Returns the memory block of a cell for writing 71 

MFop Returns/Changes the n-th operand 71 

MFopSet Sets the n-th operand of a cell 72 

MFopFree Frees the n-th operand of a cell 72 

MFopSubs Substitutes the n-th operand of a cell 72 

MFsig Recalculates the signature of a cell 72 

MFsize Gets/Changes the length of the memory block 72 

Special Objects 

MVfail Special object FAIL 74 

MVnil Special object NIL 74 

MVnull Special object null() 74 

MVfalse Boolean value FALSE 75 

MVtrue Boolean value TRUE 75 

MVunknown Boolean value UNKNOWN 75 

MVhalf Rational number | 75 

MVi Complex number I 75 

MVone Integer number 1 75 

MVone_ Integer number -1 75 

MVtwo Integer number 2 76 

MVtwo_ Integer number -2 76 

MVzero Integer number 0 76 

Operating on Strings and Identifiers 

MFlenldent Returns the length of an identifier 77 

MFlenString Returns the length of a string 77 

MFnewIdent Creates a new identifier 77 

MFnewString Creates a new string 77 

Operating on Booleans 

MFnot Negates a Boolean constant 78 

Operating on Complex and Rational Numbers 

MFcomplex Constructs a complex number 79 

MFcomplexIm Returns the imaginary part of a complex number 79 

MFcomplexRe Returns the real part of a complex number 79 

MFrat Constructs a rational number 79 
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MFratDen Returns the denominator of a rational number 80 

MFratNum Returns the numerator of a rational number 80 

Operating on Lists 

MFfreeList Frees the n-th list entry 80 

MFgetList Returns the n-th list entry 81 

MFnewList Creates an empty list 81 

MFnopsList Returns/Changes the number of list entries 81 

MFsetList Sets the n-th list entry 81 

MFsubsList Substitutes the n-th operand 81 

Operating on Expressions 

MFfreeExpr Frees the n-th operand of an expression 83 

MFgetExpr Returns the n-th operand of an expression 83 

MEnewExpr Creates an expression 83 

MEnewExprSeq Creates an expression sequence 83 

MFnopsExpr Returns/Changes the number of operands 83 

MEsetExpr Sets the n-th operand of an expression 84 

MEsubsExpr Substitutes the n-th operand of an expression 84 

Operating on Domain Elements 

MFdomExt Returns the domain of a domain element 84 

MEfreeExt Frees the n-th operand of a domain element 85 

MFgetExt Returns the n-th operand of a domain element 85 

MFnewExt Creates a domain element 85 

MFnopsExt Returns/Changes the number of operands 85 

MFsetExt Set the n-th operand of a domain element 85 

MFsubsExt Substitutes the n-th operand of a domain element 85 

Operating on Sets 

MFdelSet Removes an element from a finite set 86 

MFinSet Looks for an element in a finite set 86 

MFinsSet Inserts an element into a finite set 86 

MFintersectSet Returns the intersection of two finite sets 86 

MFlist2set Converts a finite list into a finite set 87 

MFminusSet Returns the difference of two finite sets 87 

MFnewSet Creates an empty finite set 87 

MFset21ist Converts a finite set into a finite list 87 

MFunionSet Returns the union of two finite sets 87 
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Operating on Tables 

MFdelTable Removes the table entry of a given index 88 

MFget Table Returns the table entry of a given index 88 

MFinTable Looks for a table entry under a given index 88 

MFinsTable Inserts a table entry under a given index 88 

MFlist2table Converts a list of equations into a table 88 

MFnewTable Creates an empty table 88 

MFtable21ist Converts a table into a list 88 

Operating on Domains 

MFdelDomain Removes the domain entry of a given index 89 

MFgetDomain Returns the domain entry of a given index 89 

MFinsDomain Inserts a domain entry under a given index 89 

MFnewDomain Creates respectively returns a domain 90 

MVdomain The current module domain 90 

MVdomkey Name/Key of the current module domain 90 

Operating on Arrays 

MFarray21ist Converts an array into a list 91 

MFdim Array Returns the dimension of an array 91 

MFlist2array Converts a list into an array 91 

MFrangeArray Returns the range of a specific dimension of an array . . 92 

Operating on Polynomials 

MFlist2poly Converts a list into a polynomial 92 

MFpoly21ist Converts a polynomial into its list representation 93 

MFdegPoly Returns the total degree of a polynomial 93 

Calling Built-in and Library Functions 

MFcall Calls a MuPAD function 95 

Evaluating Objects 

MFeval Evaluates an object 96 

MFexec Executes an object 96 

MFtrap Executes an object in the context of traperror 96 

MFread Reads and executes a MuPAD program 96 
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Accessing Variables 

MFgetVar Returns the value of a MuPAD variable 97 

MFdelVar Removes a MuPAD variable 98 

MFsetVar Assigns a MuPAD variable a value 98 

Basic Arbitrary Precision Arithmetic 

MFadd Adds two numbers 99 

MFaddto Adds two numbers 99 

MFmult Multiplies two numbers 99 

MFmultto Multiplies two numbers 99 

MFdec Decrements a number 99 

MFdiv Divides two numbers 99 

MFdivto Divides two numbers 99 

MFdivInt Integer division of two numbers 99 

MFinc Increments a number 100 

MFmod Computes the positive modulus of two numbers 100 

MFmods Computes the symmetrical modulus of two numbers . . 100 

MFpower Computes the power of two numbers 100 

MFsub Subtracts two numbers 100 

MFsubto Subtracts two numbers 100 

Transcendental and Algebraical Functions 

MFbinom Binomial coefficient of two numbers 100 

MFexp Exponential function 101 

MFgcd Computes the gcd of two numbers 101 

MFlcm Computes the 1cm of two numbers 101 

MFln Natural logarithm 101 

MFsqrt Computes the square root of a number 101 

Special Arithmetic Functions 

MFabs Absolute value of a number 101 

MFisNeg Checks if a number is negative 101 

MFneg Negates a number 102 

MFrec Reciprocal value of a number 102 

Displaying Data 

MFout Displays a MuPAD object 103 

MFprintf Displays C/C++ data 103 

MFputs Displays a C/C++ character string 103 
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Allocating Memory 

MFcfree Frees a memory block 104 

MFcmalloc Allocates a memory block 104 

Kernel and Module Management 

MCmodule Name of the current module domain 105 

MFdisplace Displaces a module 105 

MFglobal Declares a global MuPAD variable 105 

MFstatic Changes the module attribute ’static’ 106 

MFterminate Terminates the MuPAD Kernel 106 

MFuserOpt Returns the string of user kernel options 106 

Data Type Definitions 

MTbool Internal data type for C/C++ Booleans 108 

MTcell Internal data type of a MuPAD memory cell 108 

Meta Types 

MCchar Meta Data Type: character based types 108 

MCinteger Meta Data Type: integer numbers 108 

MCnumber Meta Data Type: any numbers 108 

Module Function Attributes 

MChidden Module function attribute: hidden function 109 

MChold Module function attribute: option hold 109 

MCnop Module function attribute: no option 109 

MCremember Module function attribute: option remember 109 

MCstatic Module function attribute: static function 109 

The Copy and Address Attribute 

MCaddr Copy mode: address 110 

MCcopy Copy mode: copy 110 

Internal Boolean C/C++ Constants 

MCfalse Internal Boolean C/C++ constant: false 110 

MCtrue Internal Boolean C/C++ constant: true 110 

MCunknown Internal Boolean C/C++ constant: unknown 110 
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Empty MuPAD cell 

MCnull Empty MuPAD object Ill 

Defining Module Procedure and Expressions 

MPROC Defines a module procedure 114 

MEXPR Defines a module expression 114 




E. Glossary 



aging 

basic domain 
built-in function 

CAS 

C-caller version 
displacement 

domain 

domain element 
dynamic library 



A displacement strategy for dynamic modules. 

They are automatically displaced if they were not used 
for a user-defined amount of time. Refer to section 
4.7.2. 

Basic data type of MuPAD. See table 4.1 for basic do- 
mains supported by MAPI. Also refer to domain. 

A function which is defined in the MuPAD kernel. 
Built-in functions are written in C/C-h+. Also refer to 

module function. 

The abbreviation of computer algebra system. 

The MuPAD kernel in form of a machine code library 
which can be linked into a user’s application. 

To unload a dynamic module, i.e. to unlink and re- 
move it from memory. Modules can be unloaded by 
the user as well as by automatical displacement and 

replacement strategies of the module manager. 

A data structure (D0M_D0MAIN) for user-defined data 
types in MuPAD. It is also used to represent library 
packages and modules. Refer to the MuPAD User’s 
Manual [50] section 2.3.18 for detailed information. 

An element of a constructed or user-defined data type 

(domain) in MuPAD. 

A special kind of a machine code library (also refer to 
PIC). It can be dynamically linked to a program 
during run-time. 
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dynamic linking 

dynamic module 

evaluation 

flatten 

frontend 

function 

GNU 

kernel 

kernel routine 
kernel variable 
library 

library function 
library package 

linking 



A dynamic library can be linked into a program or 
a process at run-time. Under special technical condi- 
tions, such a library can be unlinked and removed from 
the memory at run-time. 

A special kind of a dynamic library which contains 
so-called module functions. It can be loaded into 
Mu PAD and used similar to a library package. Dy- 
namic modules can be displaced at run-time. 

To evaluate a Mu PAD expression -which is represen- 
ted as a tree- means to derive it by visiting each node 
recursively and substituting it with its derivation. 

In Mu PAD expression sequences and function argu- 
ments are flattend in the sense, that an expression 
1 , (a,b) ,2 is transformed into 1 ,a,b,2. 

Technical term for the user interface of a program. 

In the context of this book, the term function is used 
with a special meaning. Refer to MuPAD function 
and routine. 

Read the GNU General Public License at the Internet. 

This is the heart of the MuPAD system. It defines the 
MuPAD programming language as well as the built-in 
functions for manipulating symbolic expressions and 
doing arbitrary precision arithmetic. 

Internal C/C-h+ routine of the MuPAD kernel. 

Internal C/C-f-f- variable of the MuPAD kernel. 

This is either a dynamic library, static library or 
MuPAD library. 

A function of a library package. It is written in the 
MuPAD programming language. 

A collection of library functions. A package pack can 
be loaded within a MuPAD session using the command 
loadlib("pack") ;. 

Means to glue together machine code into an execut- 
able program or a dynamic library. 
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logical copy 
MAPI 

MAPI constant 

MAPI routine 

MAPI type 

MAPI variable 

MAPI meta type 

mmg 

module 

module function 
module generator 

module manager 
MuPAD function 

MuPAD library 
PARI 

PIC 



Logical copies are needed if multiple instances of one 
physical object are used. Making a logical copy incre- 
ments the reference counter of an object in order to 
register the new reference to it. 

The abbreviation of MuPAD Application Programming 
Interface. It performs the user’s interface to internal 
routines and variables of the MuPAD kernel. 

A C/C+-f constant defined by MAPI. The name al- 
ways starts with the prefix MC. 

A C/C++ routine defined by MAPI. The name always 
starts with the prefix MF. 

A C/C++ data type definition defined by MAPI. The 
name always starts with the prefix MT. 

A C/C++ variable defined by MAPI. The name al- 
ways starts with the prefix MV. 

Represents a set of MuPAD basic domains and can 
be used for fast and convenient type checking. 

Refer to module generator. 

This can be a dynamic module, static module or 
pseudo module. Also refer to section 4.7.1. 

A MuPAD function defined in a module. 

The tool to create a loadable and executable module 
from a C/C++ module source code file. It uses a usual 
C++ compiler and linker for this. 

The part of the MuPAD kernel which loads, unload 
and administrates modules. 

Any function available within a MuPAD session. This 

can be a built-in function, library function or 
module function. Also refer to routine. 

Collection of library packages. It contains most of 
the mathematical knowledge of the CAS MuPAD. 

The arbitrary precision arithmetic package used by 
MuPAD. Refer to the User’s Guide to PARI-GP [4] for 
detailed information. 

Abbreviation of position independent code. Typically, 
a dynamic library is compiled as PIC to enable pro- 
grams to dynamically link it. Also read section 8.3. 
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pseudo module 

physical copy 
reference counter 

replacement 

routine 

signature 

static library 
static module 

unique data 

weak unique data 



A module which is statically linked into the Mu PAD 
kernel at compile-time. It simulates a dynamic mod- 
ule on platforms which does not support dynamic 
linking well. 

Dublicates an object by copying its memory blocks. 

It is used to manage a (weak) unique data represent- 
ation of Mu PAD objects. Making a logical copy of a 
MuPAD object (MFcopy) increments the counter. It is 
decremented when the object is freed using the routine 
MFfree. 

Displacing a module in order to replace it by an- 
other one. The module manager replaces modules if 
system resources run short. 

In the context on this book, routine always refers to a 
C/C-I-+ subroutine. It can either be a kernel routine 
or a MAPI routine. 

A hash value. It speeds up the comparison of MuPAD 
objects. After changing a MuPAD object on a C/C++ 
level the MAPI routine MFsig must be used to recal- 
culate and update its signature. 

An archive of machine code routines. 

A dynamic module carrying the attribute static, 
which protects it from being displaced. 

Objects exist only once. All copies of objects are lo- 
gical copies using a reference counter system. 

Similar to unique data, but also two or more physic- 
ally copies of an object may exist. It is used because 
sometime it is too expensive to create a real unique 
data representation. 
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